Re: Doxygen comments in C++ source

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.
>>
>>
>>
>>
>