Page MenuHomePhabricator

Review and improve EFL references API documentation
Closed, ResolvedPublic

Description

The goal is to cover mostly the new EFL API, but fixes on the doxygen tree are also usefull. The new API is documented in .eo files inside efl.git, but not all of them are useful. The priority should be given on the src/lib/efl and src/lib/eo directory. Then only the file starting by efl_ in src/lib/ecore, src/lib/edje, src/lib/elementary and src/lib/ecore_con . Some of this function are loosily documented and should clearly be improved. Some have a documentation that is also not in proper English and should get fixed.

If there is limitation on the documentation system or request for improvement that would give better result, @q66 is the developer of that infrastructure.

q66 added a comment.Aug 3 2017, 6:05 PM

we should also figure out how to integrate the doxygen docs and the dokuwiki, because having two separate systems is just bad...

currently i have two possibilities in mind

  1. parse doxygen comment thingys ourselves and generate dokuwiki pages out of it, similarly to how eo docs are generated... this is somewhat difficult as it needs reimplementation of doxygen markup/commands as well as basic parsing of C and integrate that with the dokuwiki docs by doing some kind of reverse-lookup from C name to Eo stuff (could be done by adding reverse-lookup APIs to libeolian...), the need to parse Doxygen markup could possibly be alleviated by transitioning our Doxygen-style docs to Markdown, which Doxygen supports since some versions ago - then an existing Markdown parser could be used...
  1. use doxygen to process existing docs into XML output (doxygen has that) and parse the XML output and do the same reverse lookups to match things accordingly...

We'll also need to figure out how to properly integrate our Eo docs with C docs so that the UX is good and it's intuitive. That's a whole separate problem and will also need to be addressed...

zmike added a project: efl.Aug 22 2017, 3:36 PM

@q66, I fully agree with you. I am leaning toward 2. strongly and created a subtask separately: T6126 .

cedric added a comment.Oct 2 2017, 1:44 PM

This task is mostly to fill time when waiting for answer on other topics. So in priority order what need to be looked at is :

src/lib/eo/efl*.eo
src/lib/efl/interfaces/efl*.eo
src/lib/ecore/efl*.eo
src/lib/evas/canvas/efl*.eo
src/lib/ecore_con/efl*.eo
src/lib/edje/efl*.eo
src/lib/elementary/efl*.eo

With an exception for everything related to *model* and *view* at the moment.

ajwillia.ms closed this task as Resolved.Jan 4 2018, 7:39 AM
ajwillia.ms claimed this task.
ajwillia.ms added a subscriber: ajwillia.ms.

last .eo files merged today.
The doxygen integration remains, I will ensure there is a separate ticket.