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. 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? 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. 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. 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
