On Thu, 6 Nov 2014 20:38:34 -0200 Felipe Magno de Almeida <felipe.m.alme...@gmail.com> said:
> On Thu, Nov 6, 2014 at 5:09 AM, Carsten Haitzler <ras...@rasterman.com> wrote: > > i thought i'd start this here for a wide audience. > > > > documentation for efl. it's rather horrible. and yesterday it dawned on > > me... > > Hello raster, > > > this is a start - what do people have to add/say? > > > > do you have something ... better? can you improve the above? > > I'm going to say what I think is plausible solution to the > documentation problem we have today in EFL and Elementary. I don't > think it is better, but I think it is doable and is going to help the > project get users sooner rather than later. > > First of all, documentation was already problematic, but Eolian surely > made it much worse. It made it worse because it made EFL more usable > in contexts where it was not, but neither documentation nor tools > accompanied this widening of the EFL's horizont. > > I think we can still leverage on the current tools to create at least > good enough documentation, which we're still far away. If we can make > people *wink* *wink* work on Eolian to allow documentation from > multiple languages, by, e.g., tagging paragraphs per programming > language, we can generate doxygen, jsdoc, for each language. have you run "make doc" on efl lately? it takes longer than efl does to compile. a full "from scratch" compile. (actually it segfaults on arch - i can't build docs at all .. after 30seconds). elementary is worse. by a massive margin. it's at the point where the feedback cycle is useless. seeing the results of what you fixed takes forever. its totally discouraging. i think we just need to dump doxygen entirely as this is a major factor stopping people from doing anything. i look at it and go "shit - well there goes my day and i won't get a lot done" so i find something more productive to do. > I like the idea of adding a space for comments and discussions and > this can be added to generated documentation with not that much > effort. For doxygen, at least, we can generate XML and use XSLT -> > DocBook to generate very high quality documentation that can be very > well integrated through links (for example to show documentation to > other languages as well). > > I don't think we should, not yet at least, move our documentation > outside our code base in EFL. And the reason is that this is too huge > a task and requires EFL maintaining and developing a Web application. > If we're already lacking people to just write documentation how can we > expect to do that? thats why i was mentioning gollum - w don't maintain it. just a git repo with markdown. it has a web front-end ad a git "api" to mess with it. :) > I think it is useful to create a tool to analyze our documentation, so > we can spot easily where documentation is not being linked correctly > and where documentation is laking the most. This could even be added > to Stefan's weekly news and could even be considered for the 4 weeks > stabilizing period depending on how much a feature is lacking in > documentation. > > Also, the generators can improve documentation by using tagged > information from Eo files, such as ownership. It can warn the user > that one of the parameters, tagged with own, have to be freed by the > user for example. And this information is going to be correctly > sync'ed because otherwise most bindings would crash. > > 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. :) 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. > As for documentation that is exclusive to one language, such as > tutorials and examples. The binding maintainer can write a source code > in the target language with its documentation or a dox file. > > BTW, I'm assuming the bindings would be, someday, integrated to the > EFL tree. Which I think is a good thing. c++ are already. lua are already. others will depend on time/effort etc. but they can be. i am assuming any bindings we support in-tree will generate their own lang doc pages as above. :) > Kind regards, > > [snip] > > > -- > > ------------- 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 > > > -- > Felipe Magno de Almeida > > ------------------------------------------------------------------------------ > _______________________________________________ > enlightenment-devel mailing list > enlightenment-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > -- ------------- 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
