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. 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). -- Gustavo Sverzut Barbieri http://profusion.mobi embedded systems -------------------------------------- MSN: barbi...@gmail.com Skype: gsbarbieri Mobile: +55 (19) 9225-2202 ------------------------------------------------------------------------------ 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
