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

Simo Sorce simo at redhat.com
Fri Sep 13 13:12:58 UTC 2013


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.

-- 
Simo Sorce * Red Hat, Inc * New York




More information about the Freeipa-devel mailing list