On Thu, Nov 6, 2014 at 10:15 PM, Carsten Haitzler <ras...@rasterman.com> wrote: > On Thu, 6 Nov 2014 20:38:34 -0200 Felipe Magno de Almeida > <felipe.m.alme...@gmail.com> said:
[snip] >> Also, I agree that different languages should have separate >> documentations because too much information distracts and discourages >> the user. Specially when the information seems much more complicated >> than what he is looking for. So a python developer going through >> anything C or C++ related is going to run away pretty easy. > > so you're going to have to put this smarts into some eolian based tool as > eolian now has to be taught to deal with structs, enums etc. anyway for > js/lua/python etc. so if this has to go there to generate jsdoc ... and C/C++ > is separate, then some other lua doc thing (don't even now) then some > different > python doc? why not just generate it all at once - generate simple markdown. > :) That is indeed helpul. However we still have APIs in C headers for legacy functions. We could import those declarations to Eo files as well and generate documentation from there though, solving this problem. > keep the docs somewhere where they are community editable beyond just core > devs. if docs stay in .eo files the only peolpe able to work on them are those > with core src commit access. this isn't working. there are many reasons, but > it's failing now for years. and getting worse. Yes I agree it makes a lot easier for people outside to help us if we don't require commit access. However, the problem is that separating both complicates things way more than it looks like. Let's call EFL-docs a git repo like g...@git.enlightenment.org:core/efl-doc that contains all docs in some format (could be JSON, EOs, SQLite, etc). For example, how do we synchronize class definitions between EFL and EFL-docs? Functions are added, removed, renamed all the time. These must be kept in sync or people might not even know there's a new function to document. But, how do we manage renaming functions, if we through all documentation away from removed functions then when someone renames this function in EFL repo it is going to disappear in EFL-docs. Git helps us recover, but renaming becomes a huge pain in the ass. Also, should documentation live both in EFL eo's and EFL-docs? If yes, then there's no purpose to exist EFL-docs, since we will have to keep synchronizing between both anyway. If, on the other hand, documentation lives only in EFL-docs then we need to synchronize EFL API (as the last paragraph demonstrated) with EFL-docs, which is also complicated. Also, for auto-complete, we want reference documentation to live in source code. This helps developers use the API. So if we remove it from EO files or don't keep them in sync, this documentation is lost or becomes outdated in the generated files. Unless EFL-docs becomes a optional dependency to build EFL. The separation just makes sense because editing documentation through a web site becomes harder to synchronize with real source code. However, we could deliver an interface for editing that actually creates a phab differential where developers can review and push it. So we don't really need to separate both if we can make it easier for people to get documentation modifications accepted. About doxygen. Well, if we can move all documentation to EO files, we could drop doxygen very easily and improve compilation by a huge margin. This is a good thing. And we need a better tool to write tutorials then if we drop doxygen. Wiki's are good and easy to edit, but they aren't easy to use snippets of examples which is a necessity in tutorial documentation IMO. And examples should never live inside the documentation but be linked with snippets because examples must always be compiling and breaking when API changes. [snip] >> Kind regards, >> >> [snip] >> Kind regards, -- Felipe Magno de Almeida ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
