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

Campbell Barton ideasman42 at gmail.com
Mon May 12 07:58:19 CEST 2014

General comments for moving to a new documentation markup:

To be honest, I see no value in changing to some different markup at this point.

Searching Blender's code for "\param" gives 2801 hits, is it _really_
worth to move all these to some other format?

While Im not especially a fan of generating HTML docs, doxy has some pros...

- Its defacto standard, someone coming to our code doesn't have to
learn some new markup.
- It has working parsers, (even if we dont make much use of this at the moment).
- There is some way to validate the docs are correct (doxygen gives
warnings for docs for missing args)
- It has its own documentation (we dont need to write our own for our
own markup).
- IDE's/tools have doxygen integration (QtCreator for example does at
least, doxy autocompletes and I have quick preview of docs setup to a
key binding).
- The option of automatic generating docs is always there if someone
likes to use it.

While doxygen isnt perfect, I think we can spend our time better then
inventing some new markup and moving 1000s if lines of comments over
to that.

Other comments inline...

On Mon, May 12, 2014 at 2:07 PM, Joshua Leung <aligorith at gmail.com> wrote:
> 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).

To be clear, is this something you invented?

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

Ok, so you don't really like doxygen, (nor C++?, though not sure how
that point is relevant)

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

If there was an issue with adding doxygen markup why not say something
at the time?

As for this pre-dating doxygen use, can you point to a SHA1?, I only
noticed this recently.

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

I never found generated HTML docs, useful personally.
Probably because we aren't maintaining API docs (if we were writing
some library/SDK it would make more sense).

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

This is really subjective stuff.
But I don't share your distaste of doxy, personally I prefer RST, but
I wouldn't see moving to that as worthwhile either.

> 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
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers

- Campbell

More information about the Bf-committers mailing list