On Fri, 7 Nov 2014 12:01:19 -0200 Felipe Magno de Almeida <felipe.m.alme...@gmail.com> said:
> 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. from the interfaces work on - once it solidifies, the legacy apis and eo apis will no longer be auto-generated. the legacy apis will be manually maintained - so i'm assuming exactly this, and thus they will need some manual mapping. in this case then eolian itself doesnt need to know this - the doc tool does though. > > 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. aha! this is where i realized... functions cannot be removed or renamed. because once there they are STABLE. they must remain the same. at least once it goes into a release. so we do a generation run when we enter our "stability" period before an efl release. at this point nothing should be renamed or deleted anymore. this generation run ADDS new markdown files per new function, class, event we added. here is what i was thinking. i don't want to generate like doxygen where everything is on one page for a group. i want a class "header" markdown page. this "#includes" a class description markdown file - this class desc file is edited by humans. the header is not. its always generated. this header includes the list of classes this class inherits from, the list of funcs/properties/events - these lists are links to 1 markdown page per event, per property, per function. so that way when a NEW func is added, it's a new markdown file to edit separately. by splitting into these files and linking or "#include"-ing them you can split between generated and human edited. once a func/property/event has been generated (created) it should never again change as now its a stable api people depend on. remember i'm thinking here that we do this generation run when we go into release mode - maybe even towards the end. from this point on we then also include writing docs as part of stabilization. :) > Also, should documentation live both in EFL eo's and EFL-docs? If yes, no - this is where it just gets nasty,. if it lives in both we are having to transfer BACK from the doc repo back to the src repo AND convert the docs back into comment format. it also has to be automated. so no. i'm imagining a one way street not of docs but of skeleton definition - the prototypes of the funcs - the definitions are generated once and committed to the doc tree. this is why git as a back-end i so awesome. it makes it easy for us to simply run a script every now and again and then commit+push the new stuff. i do not think it should run every day automatically. it's done manually once per release cycle by a developer. > 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. autocomplete works just fine without any docs. you don't need docs for that. your autocomplete editor has to understand doxygen comments if it is to provide any form of docs for a function. i don't remember ever seeing this myself - just the normal autocomplete of actual funcs/macros/structs. i was thinking that the doc tree can eventually be used by an IDE (eg EDI) to make autocomplete and so on more useful. it can find the right markdown for the specific symbol you are completing if we maintain a convention. > 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. as above - don't need it. :) as it goes one way. :) > 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 that is exactly what i am imagining. for eo core (eo_add, eo_do, etc.) it's manual as well as eina - everything else eventually becomes eo based. why? because reality is that is the only way it's going to get AUTOMATIC binding to all the languages we want to support. so reality is .. eventually it will all be eo. > 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. gollum markdown can do that. you can "#include" a .c file. the doc tree can just have these .c file (or .cpp or .js or .lua or .py) files there - as plain separate files. the markdown for whatever you are documenting that includes code should do this. it also then gets color hilighted by pygments. it's ALSO separately edited from the markdown that includes it and thus is compilable on its own. :) (well ok if its a 4 line sample it likely isnt compilable on its own as it doesnt include a main() and #includes of everything etc. but we can make a parent demo.c that #includes this sample.c and the demo.c includes all the footwork to make it actually build and run). so the doc repo would contain code... but it isnt buried inside the makrdown files. it's separate src. > [snip] > > >> Kind regards, > >> > >> [snip] > >> > > Kind regards, > -- > Felipe Magno de Almeida > -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
