On Thu, 14 Oct 2010, Carsten Haitzler (The Rasterman) wrote:
> just a note.. other than hunting bugs (which i have been doing), 2 things need > doing for a release > > 1. docs (api docs). these: > > http://docs.enlightenment.org/auto/eina/ > http://docs.enlightenment.org/auto/eet/ > http://docs.enlightenment.org/auto/evas/ > http://docs.enlightenment.org/auto/ecore/ > http://docs.enlightenment.org/auto/embryo/ > http://docs.enlightenment.org/auto/edje/ > http://docs.enlightenment.org/auto/e_dbus/ > http://docs.enlightenment.org/auto/efreet/ > http://docs.enlightenment.org/auto/eeze/ > > 2. proper wiki pages per lib. these: > > http://trac.enlightenment.org/e/wiki/Eina > http://trac.enlightenment.org/e/wiki/Eet > http://trac.enlightenment.org/e/wiki/Evas > http://trac.enlightenment.org/e/wiki/Ecore > http://trac.enlightenment.org/e/wiki/Embryo > http://trac.enlightenment.org/e/wiki/Edje > http://trac.enlightenment.org/e/wiki/E_Dbus > http://trac.enlightenment.org/e/wiki/Efreet > http://trac.enlightenment.org/e/wiki/Eeze > > > the api docs need to be technical and cover core details of the library. the > wiki page should be a more general overview - with maybe some screenshots, > examples, bullet point short-list of things the library does, and anything > else > marketing-like that makes it look good. to some extent something like this is > some of the way there: > > http://trac.enlightenment.org/e/wiki/EFLOverview > > (need to fix crudely drawn diagrams). :) > > some of the wiki pages are good - mostly there, some are very empty, some > probably don't have a lot to say. but we do need to fill them in. this will be > the first thing people look at for info about libraries. get them started. > examples, things to get people excited, links to youtube videos of things > running and so on. > > 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. > 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 ? 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 > > ------------------------------------------------------------------------------ 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
