On Thu, 14 Oct 2010 07:55:51 +0200 (CEST) Vincent Torri <[email protected]> said:
> > as for api docs i'd love to at least see every api func have a template > > "fill me in" doxygen doc comment. if we can - fill them in. > > I disagree here. Having no doc for a function make doxygen display a > warning in the terminal. Which means we *know* that there is a problem and > the doc must be fixed. Otherwise we would have to read all the doc to see > if we have filled correctly or not the doc. I prefer having an automated > way of warning me about that, instead of reading the whole doc. i have tested this and it definitely doesn't. in fact its not possible for doxygen to do this. well not unless it considers EVERY function - that includes internal ones (static, inlined and just internal shared funcs) and then you'd have to pick which ones are EAPI and in the exported .h and which are not. i have tested this - doxygen says NOTHING about undocumented api's when i do "make doc". > > the problem is actually > > making useful docs that cover the wide range of things a function does - its > > side effects, relationships to other functions and subsystems etc. etc. this > > means often more than 1 sentence. it means a few paragraphs and examples of > > usage and more. > > About relationship, there is a feature in doxygen that allow a doxygen doc > refer to another doxygen doc, #EINA_FALSE in ecore would give a link to > the definition of EINA_FALSE in eina_types.h. That means that they should > be installed/untar in some known directories by advanced. Do we add > installation documentation rule ? well relationship here was only meant within 1 lib - ev evas_object_del() and how this may affect smart objects, box and table layout objects, etc. etc. as they have a smart del handler that will do certain things on delete. but it would be nice to be able to cross-link our docs. they are installed in the above dirs always by default so... i'd say its worth being able to link to "out of doc" docs via http://docs.enlightenment.org/auto/DOCNAME > Vincent > > > i don't pretend we will have everything documented by 1.0 - but i'd like to > > see as much as possible get done. at LEAST get template docs with simple > > lists of params and a 1 liner description with a "needs more" if the > > function is non-trivial. (some setters and getters are very trivial). > > > > -- > > ------------- Codito, ergo sum - "I code, therefore I am" -------------- > > The Rasterman (Carsten Haitzler) [email protected] > > > > > > ------------------------------------------------------------------------------ > > Beautiful is writing same markup. Internet Explorer 9 supports > > standards for HTML5, CSS3, SVG 1.1, ECMAScript5, and DOM L2 & L3. > > Spend less time writing and rewriting code and more time creating great > > experiences on the web. Be a part of the beta today. > > http://p.sf.net/sfu/beautyoftheweb > > _______________________________________________ > > enlightenment-devel mailing list > > [email protected] > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > > > > -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) [email protected] ------------------------------------------------------------------------------ Beautiful is writing same markup. Internet Explorer 9 supports standards for HTML5, CSS3, SVG 1.1, ECMAScript5, and DOM L2 & L3. Spend less time writing and rewriting code and more time creating great experiences on the web. Be a part of the beta today. http://p.sf.net/sfu/beautyoftheweb _______________________________________________ enlightenment-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
