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

[Dmitri Pal]

On 09/13/2013 09:12 AM, Simo Sorce wrote:
> On Fri, 2013-09-13 at 13:54 +0200, Petr Vobornik wrote:
>> 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, ...).
> Well my concern remains that if we want to change later it will take
> some effort, but I guess it is better to have improved docs now and take
> care of the 'ruby' problem later if it becomes an issue.
>
> I find it amusing we have to use ruby to document javascript though, you
> would think javascript is a good enough language to do that :-D
>
> Simo.
>
I take this as an ack for JSDuck.

-- 
Thank you,
Dmitri Pal

Sr. Engineering Manager for IdM portfolio
Red Hat Inc.


-------------------------------
Looking to carve out IT costs?
www.redhat.com/carveoutcosts/