On Mon, 25 Oct 2010 09:31:01 -0200 Gustavo Sverzut Barbieri <barbi...@profusion.mobi> said:
> On Mon, Oct 25, 2010 at 7:31 AM, Carsten Haitzler <ras...@rasterman.com> > wrote: > > On Mon, 25 Oct 2010 11:15:42 +0200 Cedric BAIL <cedric.b...@free.fr> said: > > > >> On Mon, Oct 25, 2010 at 10:26 AM, Carsten Haitzler <ras...@rasterman.com> > >> wrote: > >> > On Mon, 25 Oct 2010 09:42:43 +0200 Cedric BAIL <cedric.b...@free.fr> > >> > said: > >> >> > the html docs should work offline too... just bring up index.html in a > >> >> > browser. > >> >> > >> >> I actually think that putting in each "root" header a link to the auto > >> >> generated doc will help people that are looking at our API. We could > >> >> also take into account the version when we do a release and point them > >> >> to the right version of the doc online. This could be automatic. > >> > > >> > aaah that is indeed an issue yet undiscussed. we auto-generate docs for > >> > whatever trunk has. fine until we do evas2.0 or any api break.. as docs > >> > wont be "wrong" - they may just document new features not yet available > >> > in your versions of evas/edje/eina/whatever. so as of 1.0 we do NEED to > >> > make sure we clearly document as of when a feature is available (after > >> > 1.0 next round of features will be 1.1 - so any features and api's added > >> > need to be marked as added in 1.1). unless we want to generate new docs > >> > per minor version of evas? > >> > >> I have no strong opinion on that. The only draw back I see with online > >> docs per minor version, is how search engine would handle them. If we > >> do our job correctly, and have only one version online, people will > >> know by reading the docs when it was added to the EFL. So I am a bit > >> inclined to have only one auto build doc repository, but nothing > >> really strong on that. > > > > that would be my preference too - we just need to document features added > > and what version they were added in specifically. > > > >> > anyway - still.. the question is being tossed back and forth. we have 2 > >> > sides. in .h or not. > >> > >> > i ask this. read Eet.h - is that hard to use/read? would you prefer... > >> > Ecore.h for example? > >> > >> I tend to think that Eet.h is harder to read, but not only because of > >> the doc, but because all functions are in it, eet_image*, eet_data* > >> and so on. Having only one header per group of function help in that > >> sense. As for Ecore.h, the only think I don't like is when pointer to > >> callback function don't have a name that help understand what they do > >> (I think I did fix all case in that header). > > > > eeek! i'm the opposite! i find eina a royal pita... :) > > > >> > (actually while i'm at it.. the tonne of eina headers... i'm not too fond > >> > of.. but we won't be changing this any time soon methinks). > >> > >> In fact, my preferred header at the moment are eina :-) Divided by > >> functionalities, with some doc and tutorial where it make sense. > > > > i see we disagree there. i shall have to now beat you with a cow until you > > agree! :) > > /me beats cedric with la vache > > :) > > > >> > also one other thing. if we put API docs in the public .h - we can > >> > separately document internal info in the .c files - it's at least easier > >> > to handle doc-wise that trying to put different comment snippets within > >> > the same files in different doxygen sections (hell u'd want them in 2 > >> > separate documents at the end of the day). > >> > >> In eina, we did put the local part from the global part at the top of > >> each .c files and they are already separated from the doxygen point of > >> view. If we where considering adding documentation for the internal, > >> it wouldn't be difficult. > > > > i just noticed.. some of eina's docs are in the public headers.. look at > > eina_log.h, eina_strbuf.h and eina_list.h for examples - others are not. > > this is a bit inconsistent even within eina. some things like the macros > > can only be documented in the .h as such... that leans me more towards the > > "aaagh. for external API docs it smells like they all need to be in the > > public .h's as thats where structs are defined, macros and ... functions". > > > > so does someone have a solution for keeping the docs out of the public h's > > in the case of public structs and macros? :) if not - i suspect we'd just > > have to accept that we likely need to move them all there...? > > Yeah raster, we know you're big fan of anything that is long enough to > fit into people's mind... like seen in your long functions and all. :) > Just like Cedric, I'm much more found of Eina's docs, with split files. /me throws a cow @ gustavo > And I'd say our partial docs in .h with most of it in .c fits what > Brian suggests as user. We tried to put some "bootstrap" and leave > other stuff to .c. We could even move a bit more, like some tutorials > to .h, but leave most of the functions in .c (unless inline functions > that must stay there anyway). as for the partial docs... its not just the short forms or such - its ALL of the struct docs that are in the .h - they are nowhere else. same with macros the ENTIRE docs for the macro (as if it were a function) are in the .h - so it's not the nicer "short version of docs in h - long one in .c" its "some parts in .h, some in .c - depending on the type of things being documented (struct, macro function)" so the split is pretty much usless. -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ Nokia and AT&T present the 2010 Calling All Innovators-North America contest Create new apps & games for the Nokia N8 for consumers in U.S. and Canada $10 million total in prizes - $4M cash, 500 devices, nearly $6M in marketing Develop with Nokia Qt SDK, Web Runtime, or Java and Publish to Ovi Store http://p.sf.net/sfu/nokia-dev2dev _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
