Re: Doxygen comments in C++ source

> And, if people are putting in the effort of documenting functions / new
code, it should probably be standardised, readable, and parseable. The
standard for readable, parseable doc comments is probably doxygen. Ergo....

Yes, this is what I was trying to explain (and not doing a great job of
it). There's a lot you get with Doxygen for nearly free, enough so that IMO
it doesn't impede other efforts to add documentation. Markdown files can be
brought into the resulting documentation very easily, links to related
classes and functions are autogenerated. So, it doesn't have to be
in-source necessarily.

> There are *a lot* of contributions and engineering-hours that are impeded
or completely blocked because of "what is this argument supposed to be?"
kinds of issues - if we can put in a minimal amount of extra effort on this
front, it's incremental progress towards a more contributor-friendly
codebase.

I completely agree. Just today someone was asking me where a certain event
was happening in the codebase and I had absolutely no idea where to point
them other than to grep the source code. Which isn't very helpful when the
function that does this could be named about 5 different things, or the
code could be buried deep in a larger function.

So, going back to the original purpose of this thread, here are some more
ideas to consider:
- adding summary markdown files to help describe/orient the organization of
a directory's contents (where would they live?)
- adding top-of-file descriptions of contents/purpose (I have to say
personally this is something that would really work for me)
- for functions that ought to be refactored but aren't for whatever reason,
providing a minimum amount of documentation with a TODO for cleanup
- providing better in-source comments for code that might be confusing if
you didn't spend the last 5 hours following the same path through the
codebase the previous author did

I would also recommend as a long-term goal, getting some sort of unit test
system in place for sclang. Of course, better to make the code testable
before pinning it down with tests, but my feeling is we'll have to walk a
rope between testing for sanity/basic integration while allowing
lower-level organization to be easily rewritten if need be.

> > "code quality comes first" is only meaningful once we have standards on
"code quality". Right now the guidelines are very slim and not enough to
really amount to quality code, IMO. If you really believe this, then we
ought to spend time working on those.

> I can help with this on the sclang side, if we decide to work on this. I
think it can't be very detailed, because many of the really important
factors either are case specific or aesthetic.

Sure! We made a start at this and IMO it was very helpful. I would love to
see it continue. There's still this open issue from that wave of
consensus-gathering:
https://github.com/supercollider/supercollider/issues/2931. It could be a
good place to pick the thread back up.

I would take more of a bookkeeping role in those discussions now, I don't
have strong opinions on the sclang codebase at this point. But, I do feel
that it just makes it so much easier to review and integrate code when the
standards are explicit and the conversations about them are referenceable.

-Brian

On Tue, Feb 13, 2018 at 2:02 PM, <scott-y6qSm6YX8/[email protected]> wrote:

> Following asynth, I hate Doxygen as well - I don't think there's a huge
> benefit to having a doxygen doc for the SC internals - I rarely find myself
> searching doxygen dumps for info, unless I don't have the source locally.
>
> *However* --- Brian is right that a "clean camp" policy, asking that
> people add or clean up doc comments when they visit an area of code, would
> go along way towards a more navigable codebase. And, if people are putting
> in the effort of documenting functions / new code, it should probably be
> standardised, readable, and parseable. The standard for readable, parseable
> doc comments is probably doxygen. Ergo....
>
> One thing to keep in mind too - Doxygen isn't useful to me, nor is it
> probably useful to anyone participating in this thread. However, this is an
> open source project with a wide range of participants and
> potential-participants. There are *a lot* of contributions and
> engineering-hours that are impeded or completely blocked because of "what
> is this argument supposed to be?" kinds of issues - if we can put in a
> minimal amount of extra effort on this front, it's incremental progress
> towards a more contributor-friendly codebase.
>
> - S
>
> On Fri, Feb 9, 2018, 9:11 PM <[email protected]> wrote:
>
>> Without weighing in on what format the documentation should be in, or how
>> mandatory adding it should be, may I just say my heart leaps every time I
>> see a new explanatory comment in the server code. bce7432 and 891fcbc are a
>> couple of nice recent examples.
>>
>> Tom
>>
>>
>>
>> On Thu, Feb 8, 2018 at 4:16 PM, <julian.rohrhuber-QYZGCWsIODmAF8UT6DzBU6xOck334EZe@public.gmane.org>
>> wrote:
>>
>>>
>>> > On 08.02.2018, at 19:12, [email protected] wrote:
>>> >
>>> > > so i guess my proposal would be, write Doxygen comments if you
>>> really feel like it, but with the understanding that it's temporary. either
>>> way, code quality comes first.
>>> >
>>> > "code quality comes first" is only meaningful once we have standards
>>> on "code quality". Right now the guidelines are very slim and not enough to
>>> really amount to quality code, IMO. If you really believe this, then we
>>> ought to spend time working on those.
>>>
>>>
>>> I can help with this on the sclang side, if we decide to work on this. I
>>> think it can't be very detailed, because many of the really important
>>> factors either are case specific or aesthetic.
>>>
>>>
>>>
>>>
>>