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. > 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). > (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. > 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. -- Cedric BAIL ------------------------------------------------------------------------------ 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
