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 - [email protected] - 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 <[email protected]> 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 <[email protected]>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 >>> [email protected] >>> http://lists.blender.org/mailman/listinfo/bf-committers >>> >> >> >> >> -- >> With best regards, Sergey Sharybin >> _______________________________________________ >> Bf-committers mailing list >> [email protected] >> http://lists.blender.org/mailman/listinfo/bf-committers > _______________________________________________ > Bf-committers mailing list > [email protected] > http://lists.blender.org/mailman/listinfo/bf-committers _______________________________________________ Bf-committers mailing list [email protected] http://lists.blender.org/mailman/listinfo/bf-committers
