[Freeipa-devel] [PATCH] 451-458 Web UI devel and source code documentation

[Petr Vobornik]

On 09/12/2013 09:22 PM, Simo Sorce wrote:
> On Thu, 2013-09-12 at 14:54 -0400, Dmitri Pal wrote:
>> On 09/12/2013 09:14 AM, Simo Sorce wrote:
>>> On Thu, 2013-09-12 at 07:50 +0200, Martin Kosek wrote:
>>>> On 09/11/2013 11:24 PM, Dmitri Pal wrote:
>>>>> On 09/11/2013 12:28 PM, Simo Sorce wrote:
>>>>>> On Wed, 2013-09-11 at 12:44 +0200, Petr Vobornik wrote:
>>>>>>> Hello,
>>>>>>>
>>>>>>> This is a part of documentation effort which started couple month
>>>>>>> ago.
>>>>>>> Attached patches improves devel documentation of Web UI. Mostly by
>>>>>>> annotating source code and then processing it by JSDuck tool[1].
>>>>>>>
>>>>>>> The documentation is not complete - most plugins and member of some
>>>>>>> core
>>>>>>> widgets and facets are not annotated yet. I'm sending it now because
>>>>>>> I
>>>>>>> need to focus on more pressing tickets.
>>>>>>>
>>>>>>> You can see current state at my fedorapeople page [2].
>>>>>>>
>>>>>>> I also converted 5 guides/articles which I wrote some time ago.
>>>>>>> Guides
>>>>>>> are also part of the JSDuck app [3].
>>>>>>>
>>>>>>> The idea is to regularly generate the doc and place it on
>>>>>>> docs.freeipa.org (not in production at the moment) so all doc would
>>>>>>> be
>>>>>>> on one place.
>>>>>>>
>>>>>>> Installation of JSDuck is documented on their page [4]. Basically it
>>>>>>> requires ruby and JSDuck gem.
>>>>>>>
>>>>>>> Usage:
>>>>>>> $ cd install/ui/doc
>>>>>>> $ make
>>>>>>>
>>>>>>> Documentation is generated into: install/ui/build/code_doc directory
>>>>>>>
>>>>>>> [1] https://github.com/senchalabs/jsduck
>>>>>>> [2] http://pvoborni.fedorapeople.org/doc
>>>>>>> [3] http://pvoborni.fedorapeople.org/doc/#!/guide
>>>>>>> [4] https://github.com/senchalabs/jsduck/wiki/Installation
>>>>>> I would rather not grow a dependency on Ruby in the freeIPA project.
>>>>>> Are there any alternatives ?
>>>>>>
>>>>>> Simo.
>>>>>>
>>>>> Is it dev side dependency? We might have issues if we need gems during
>>>>> build process that are not a part of distro.
>>> This is only one of the problems.
>>>
>>>> This a UI Doc building dependency, i.e. not needed when package is installed.
>>>> So someone/something doing a release and releasing the doc will need the ruby +
>>>> respective rubygem installed.
>>>>
>>>> If we want to automate the build and let the doc be built for example on koji,
>>>> I am afraid we would have to step back from using jsDuck, or let Petr package
>>>> it in Fedora since he used it despite my previous warnings :-)
>>> The problem is that ruby is still a fast moving target, and we do not
>>> want to waste time fighiting it when (not if) it will break and you find
>>> it just right before a release where you want to build docs.
>>>
>>> I really would like to avoid dependencies in Ruby in this project
>>> completely as long as possible.
>>>
>>>> Petr, we should think if we should keep UI doc and articles in devel repo or if
>>>> leave just the anonated code there and move all development articles and guides
>>>> to our new doc repo
>>>> http://www.freeipa.org/page/Contribute/Documentation
>>> moving to the doc repo does not solve the problem, really, we are still
>>> depending on a) ruby for generating docs, b) someone knowing Ruby to fix
>>> things when they will break.
>>>
>>> Simo.
>>>
>> It seems that doxygen does not work for JS for us.
>> So it is node.js vs. ruby vs. no generated docs.
>> Since we always can get back to "no docs" if things go really wrong I do
>> not see it as an option here.
>> I do not like either of the other two alternatives. And I do not know
>> which one would be best if any.
>
> the probelm, if I understood it correctly is that each of this systems
> have a different markup language, so switching later would mean also
> changing all the markup language in the code, high churn and lot of
> wasted work. I am assuming you use javadoc with javascript with doxygen,
> what does jsduck uses ?

jsduck, yuidoc, jsdoc and doxygen use some flavor of javadoc. They are 
not compatible though. With regular expressions, existing comments can 
be easily converted ie. into yuidoc. But it would still require some 
additional work because jsduck leverages code introspection, but most of 
the others doesn't so one would have to add the missing information.

>
> Or are we trying to generate just lists of functions from the actual
> code ? What is the value if there is no associated description of what
> the function does ?
>
> Simo.
>
It's not just list of members. Added values (general and some jsduck 
specific):

- list of classes grouped by usage (main page)
- list of events which might not be regular member (just a documented one)
- descriptions for functions and properties where purpose is not clear 
from their name
- examples of usage for some classes/members
- inheritance chain parent class, mixin classes, subclasses
- info about which parent's method was overridden by a method
- search (classes, members; doesn't require server side)
- filter by member name
- filter by member type: deprecated/protected/public/inherited
- guides where you can write: 'classname.membername' and it will 
automatically make you a link do relevant doc
Doc build checks:
- check if documented type is declared
- check if member has description
- check if annotation has correct format
- check if member belongs to declared class
- check if overriden member exists
- duplicate members, params

Not sure if I should elaborate more on usecases (experiences devel vs 
web ui newbie, ...).
-- 
Petr Vobornik