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

Reply via email to