From: Carsten H. (T. R. <ra...@ra...> - 2011-05-24 23:21:14
|
On Tue, 24 May 2011 14:59:49 +0200 (CEST) Vincent Torri <vt...@un...> said: > > > On Tue, 24 May 2011, Cedric BAIL wrote: > > > On Tue, May 24, 2011 at 1:59 PM, Vincent Torri <vt...@un...> wrote: > >> On Tue, 24 May 2011, Daniel Juyung Seo wrote: > >>> It's already done in other libs such as evas, edje, eina, ... > >>> > >>> And ecore has missing documentations on the website due to this. > >>> http://docs.enlightenment.org/auto/ecore/ > >>> Compare this with Evas documentation. > >>> http://docs.enlightenment.org/auto/evas/ > >> > >> i would like to do the contrary for all the libraries : having a .dox file > >> in doc/. One of the reason is to update the version number automatically > >> with configure. See line 13 of the current Ecore.h. The other solution > >> would be to have an Ecore.h modified by configure, and I don't like this. > >> > >> The other reason is to not pollute the main header with such doc and to > >> actually give a documentation of all the components of an EFL in a single > >> or several dox files > > > > I don't know much about your plan, idea, but one of the good point of > > moving doc to header, is that we could generate doc with just the > > header (so any distribution that provide a dev package, can be the > > source of a local doxygen doc). > > you're dreaming :) All the html / css stuff is in doc/ so it's utopic to > think that with just the header, we can generate a good doc. > > Imho, the header should just contain the API doc and eventually a > tutorial. That's what I did for eina, but i'm more and more onvinced hat > tutorials should go outside the source files (.h or .c) we can have pretty much all the docs in the headers, EXCEPT when we need external files for the docs. this means images/diagrams or code samples YOU CAN COMPILE (tutorials). generating a single doc from all installed headers is easy enough for EFL right now. we DO need a general doc template and frankly our doc template (header.html, footer.html, css etc.) is closely tied to the website, NOT the library itself. actually we should probably remove all that stuff from the doc dirs themselves and make it part of www, and the doc dirs per project now just contain tutorials & examples. technically we CAN install these too - eg in PREFIX/share/doc/LIBNAME and then generating docs with proper and easy crosslinking between efl libs is easy. -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ra...@ra... |