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.
[...]
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
