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

Sergey Sharybin sergey.vfx at gmail.com
Sun May 11 22:24:09 CEST 2014


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


More information about the Bf-committers mailing list