On Wed, 28 Jul 2010 23:46:01 -0300 Gustavo Sverzut Barbieri <barbi...@profusion.mobi> said:
> On Wed, Jul 28, 2010 at 10:56 PM, Michael Blumenkrantz > <m...@zentific.com> wrote: > > As many of you are aware, much of our documentation ranges from being > > somewhat poor to nonexistent. If we are seriously considering any sort > > of release in the near future, as we seem to be gearing up for with > > things like official code formatting, we need to fix this. > > > > I propose that as of now, patches implementing new EAPI functions which > > are not accompanied by appropriate doxygen docs be rejected until the > > docs have been written. This will cut down on the work for people like > > me, who have been actively trying to fill in the gaps. > > > > I cannot be everywhere to babysit all commits and write READABLE docs > > for them, nor do I want to. > [...] i agree - and documentation != "write the function name in english". efl function names, enums, etc. are very long and descriptive. this alone limits the need for documentation - but docs that simply re-write this already given info are pointless. docs need to cover pre and post conditions side-effects, assumptions, intended use scenarios and probably even an example of how to se the call - maybe in multiple scenarios. > Excellent mail Michael! > > To better define what is a READABLE (and useful) documentation, please > document the assumptions such as pre and post conditions: > > - is it a pointer? can it be NULL? what is the effect of NULL? > what's the effect of non-NULL? (let's save some crashes!) > > - is the pointer const? make sure no reference is taken, if it is, > document this (often we allow const void*data for callbacks, the > references are taken, although not touched directly) If it is a > stringshare, make it clear so people may benefit from it (ie: > eina_stringshare_ref() is much cheaper than eina_stringshare_add()) > > - is the pointer not const? do you keep a reference? steal it? why > is it not const? what are the consequences? > > - is it a return? should the user free it? how to free it? plain > free() or some other call? > > - add @see for "see also" referring to similar functions (ie: > eina_stringshare_add() should refer to eina_stringshare_add_length()) > or complimentary (ie: eina_stringshare_add() should refer to > eina_stringshare_del() and eina_stringshare_replace()). > > - last but not least: document some special behavior of the > function. Yes, the name should say it all, but sometimes we just say > "sort" but do not specify the algorithm, so eina_list_sort() says the > complexity of the worst case, it also say the sort is in-place, etc. > > > I hope it help, and that Michael can keep his pace... because I did > lots of docs but then gave up :-P > > -- > Gustavo Sverzut Barbieri > http://profusion.mobi embedded systems > -------------------------------------- > MSN: barbi...@gmail.com > Skype: gsbarbieri > Mobile: +55 (19) 9225-2202 > > ------------------------------------------------------------------------------ > The Palm PDK Hot Apps Program offers developers who use the > Plug-In Development Kit to bring their C/C++ apps to Palm for a share > of $1 Million in cash or HP Products. Visit us here for more details: > http://p.sf.net/sfu/dev2dev-palm > _______________________________________________ > enlightenment-devel mailing list > enlightenment-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ The Palm PDK Hot Apps Program offers developers who use the Plug-In Development Kit to bring their C/C++ apps to Palm for a share of $1 Million in cash or HP Products. Visit us here for more details: http://p.sf.net/sfu/dev2dev-palm _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
