On Wed, 10 Aug 2011 12:14:48 -0700 "Enlightenment SVN" <no-re...@enlightenment.org> 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. ------------------------------------------------------------------------------ uberSVN's rich system and user administration capabilities and model configuration take the hassle out of deploying and managing Subversion and the tools developers use with it. Learn more about uberSVN and get a free download at: http://p.sf.net/sfu/wandisco-dev2dev _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
