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

[Ton Roosendaal]

Hi Joshua,

I agree that Doxy is ugly, you can decide to not use it.
But, having each coder use own ideas of documentation formatting is not working either.

I then would like to see a project-wide consensis about it first.

-Ton-

--------------------------------------------------------
Ton Roosendaal  -  ton at blender.org   -   www.blender.org
Chairman Blender Foundation - Producer Blender Institute
Entrepotdok 57A  -  1018AD Amsterdam  -  The Netherlands



On 12 May, 2014, at 6:07, Joshua Leung 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).
> 
>  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
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers