Re: [E-devel] E SVN: glima trunk/ecore/src/lib/ecore

[Mike B. <mi...@ze...>]

On Wed, 10 Aug 2011 12:14:48 -0700
"Enlightenment SVN" <no-...@en...> wrote:

> Log:
> [ecore] Put order in header file, splitting function groups in contiguous
> chunks. 
>       Sorry for having to pratically rewrite the header, but the other way
>       to get docs right would be to put lots of @addtogroup around several
>       chunks of the file, which is ugly too and doesn't organize anything.
>   
>       I have tested ecore with that and it seems to be okay.
>   
>   
> 
> Author:       glima
> Date:         2011-08-10 12:14:48 -0700 (Wed, 10 Aug 2011)
> New Revision: 62307
> Trac:         http://trac.enlightenment.org/e/changeset/62307
> 
> Modified:
>   trunk/ecore/src/lib/ecore/Ecore.h trunk/ecore/src/lib/ecore/ecore.c
> trunk/ecore/src/lib/ecore/ecore_app.c
> trunk/ecore/src/lib/ecore/ecore_events.c
> trunk/ecore/src/lib/ecore/ecore_exe.c trunk/ecore/src/lib/ecore/ecore_glib.c
> trunk/ecore/src/lib/ecore/ecore_idle_enterer.c
> trunk/ecore/src/lib/ecore/ecore_idle_exiter.c
> trunk/ecore/src/lib/ecore/ecore_idler.c trunk/ecore/src/lib/ecore/ecore_job.c
> trunk/ecore/src/lib/ecore/ecore_main.c trunk/ecore/src/lib/ecore/ecore_pipe.c
> trunk/ecore/src/lib/ecore/ecore_poll.c
> trunk/ecore/src/lib/ecore/ecore_throttle.c
> trunk/ecore/src/lib/ecore/ecore_time.c
> trunk/ecore/src/lib/ecore/ecore_timer.c 
In the beginning Raster created the ecore source and the headers. Now the
headers were docless and barren, darkness was over the surface of the header
files, and the Spirit of Raster was cackling with trollish glee.

And glima said, “Let there be comments,” and there were comments. glima saw
that the comments were good, and he separated the comments from the darkness.
glima called the comemnts “docs,” and the darkness he called code.” And
there were typedefs, and there were functions—the first changes.

And glima said, “Let there be a second asterisk after the first to separate
comments from docs.” So glima made the second asterisk and separated the
docs under the asterisk from the comments above it. And it was so. glima called
the new comments “doxygen.” And there was /**, and there was */—the
second changes.

And glima said, “Let the comments above the asterisks be gathered to one place,
and let large block docs appear.” And it was so. glima called the large block
docs "groups,” and the gathered comments he called "copyright notices.” And
glima saw that it was good. Then glima said, “Let the groups produce
information: sentences and phrases in the large block docs that bear details
and nuances in it, according to their various kinds.” And it was so. The groups
produced information: sentences bearing details according to their kinds and
phrases bearing nuances with questionable usefulness in it according to their
kinds. And glima saw that it was good. And there was @defgroup, and there was
@ingroup—the third changes.

And glima said, “Let there be newlines in the space between */ and /** to
separate the comments from the code, and let them serve as breaks to mark
places to stop reading, and functions and typedefs, and let them be oases in
the large doc blocks to give readability to the headers.” And it was so. glima
made two great separators-the double newline to govern the separation of groups
and the single newline to govern the separation of comments. He also made the
single line comments. glima set them in the large doc blocks to give more
readability to the headers, to govern the small bits of code and the large, and
to separate comments from darkness. And glima saw that it was good. And there
was \n, and there was \n\n—the fourth day.

And glima said, “Let the docs teem with @ signs, and let coherency flow
through the headers across the large doc blocks.” So glima created the great
ascii 64 in the doxygen and every keyword with which the doxygen teems and that
moves about in it, according to their kinds, and every word be placed
appropriately so as to be coherent. And glima saw that it was good. glima
blessed them and said, “Be fruitful and increase in number and fill the doxygen
in the comments, and let the coherency increase in the headers.” And there were
keywords, and there was occasional punctuation—the fifth changes.

And glima said, “Let the large doc blocks produce enumeration of function
attributes according to their prototypes: the @brief, the short details which
can be used for tooltips, and the @params, each according to its kind.” And it
was so. glima made the @brief according to their kinds, the @params according
to their kinds, and all the @return according to their kinds. And glima saw
that it was good. Then glima said, “Let us make further descriptions in our
docs, in our comments, so that they may elaborate upon the doxygen keywords
with coherency, over the @brief and the @params, and over all the @returns that
exist in the headers.”

   So glima created descriptions in his own docs,
   in the comments of glima he created them; 
   helpful and unhelpful he created them.

glima blessed them and said to them, “Be fruitful and increase in number; fill
the header and subdue it. Rule over the keywords in the doxygen and the
coherency in the large doc blocks and over every @return that exists in the
header.” Then glima said, “I give you every detail-bearing sentence on the face
of the whole header and every phrase that has words with nuance in it. They
will be yours for substance. And to all the doxygen keywords of the header and
all the coherency in the large doc blocks and all the @returns in the
doxygen—everything that has the slightest structure to it—I give every type for
substance.” And it was so. glima saw all that he had made, and it was very
good. And there was elaboration, and there were examples—the sixth changes.

Thus the source and the headers were completed in all their vast array. 

By the seventh hour glima had finished the work he had been doing; so on the
seventh hour he rested from all his work.  Then glima blessed the seventh hour
and made it holy, because on it he rested from all the work of creating that
he had done.
-- 
Mike Blumenkrantz
Zentific: Coding in binary since '10.