[Bf-committers] API comments (doxygen use?)

[Joshua Leung]

Hi Campbell,

My position on these matters is as follows:
  1) IMO, the syntax in question has clear benefits [1] over most of
the other documentation/markup techniques
available now. Obviously I am biased about this. Having said that,
barring compelling alternatives, I maintain
the view that this should see widespread adoption (and not just by Blender).

  2) Absolutely **anything** is better than using Doxygen. Sphinx too
falls victim to some of the very issues
that plague Doxygen, though at least tags are more easily discernable
there. Nevertheless, between C++ and
Doxygen, C++ doesn't look all that bad all of a sudden, and that's
saying quite a lot.

  3) The "introduction" of this into Blender's source code is not a
particularly new development. In particular,
it predates both the forced introduction of extensive Doxygen markup
into various headers AND the creation
of those particular style guides.

  4) Regarding "automated documentation generation systems" - I'm not
a big fan of generating piles of disembodied HTML
files, complete with elaborate formatting either. IMO, "code
documentation" should be exactly that: documentation
*about* the code, that is meant to be read *in* the code, by coders
*working on* (or using) said code. Anything which
attempts to go beyond that by adding frivolous fluff (i.e. full HTML
styling flexibility, formatting instructions for
controlling how some markup processor formats the content for display
in another medium, and clutter introduced by
adding "hints" for said dumb processor to recognise links) is
unnecessary clutter which detracts from the real purpose
of doing this in the first place. Doxygen and co fail miserably on
this front; they are focussed on the wrong problem
(i.e. that of "making life easy for the machine") instead of serving
the true audience that these tools were meant to
be serving (i.e. "us") all along.

The syntax + system in question here is thus orientated first and
foremost towards providing a structured way for
coders to note down important information about their code - in
particular, clarifying and communicating things for
which the underlying languages have no notation for (e.g. the
input/output roles of function arguments, ranges and limits on numeric
parameters, types of parameters for dynamically/untyped languages
including Python and C-Macros, and semantic meanings of different
parameter values) and also for drawing attention to critical concerns
that callers of the code should
be aware of (which can get lost in long textual descriptions, as is
common with just purely plain text methods). Compared
the verbosity of other developer-orientated techniques such as
NaturalDoc or TomDoc, the syntax here tries to achieve a
balance between clarity/readability and compactness (as the focus
should still be on the actual code) by using structure and
iconography to communicate common structural concepts and information,
allowing users to dedicate more time to focussing on
the actual quirks that the documentation is supposed to be pointing
out. Perhaps the only downside to this system at the moment
is that it currently lacks the parsing/processing backend (though
building one should not be a challenge should the need arise),
as having standalone HTML docs was never a primary concern at any
stage in its development.



Regards,
Joshua

Links:
[1] http://aligorith.blogspot.co.nz/2011/03/documenting-code-alternative-to.html

On Mon, May 12, 2014 at 8:24 AM, Sergey Sharybin <sergey.vfx at gmail.com> wrote:
> Personally i'm not so much fond of using automatic docs generation layouts
> in code. They might make things easier to parse with automated system, but
> certainly does not help human readability. Would rather avoid making it
> some sort of global obligation to use.
>
> As for the syntax used for comments, agree with Campbell. Let's be
> consistent and not mix styles.
>
>
> On Sat, May 10, 2014 at 1:17 AM, Campbell Barton <ideasman42 at gmail.com>wrote:
>
>> Hi, this mail is regarding some of Joshua's recent commits, but
>> thought it could go to the list,
>>
>> Recently I noticed comments with a different kind of syntax committed to
>> git,
>>
>> /* typedef for channel rearranging function
>>  * < list: list that channels belong to
>>  * < island: island to be moved
>>  * > return[0]: whether operation was a success
>>  */
>>
>>
>> Instead of doxygen which would look more like...
>>
>> /**
>>  * typedef for channel rearranging function
>>  * \param list: list that channels belong to
>>  * \param island: island to be moved
>>  * \return whether operation was a success
>>  */
>>
>>
>> Is this apart of some new documentation generator?
>>
>> Currently our convention is to either use plain text, or doxygen
>> formatting if more structured formatting is desired.
>>
>> As noted in our style guide:
>> http://wiki.blender.org/index.php/Dev:Doc/Code_Style#API_Docs
>>
>>
>> If there is some proposal to move to another system can this be made
>> first before introducing it into Blender's code?
>>
>> --
>> - Campbell
>> _______________________________________________
>> Bf-committers mailing list
>> Bf-committers at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-committers
>>
>
>
>
> --
> With best regards, Sergey Sharybin
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers