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

[Ana Krivokapic]

On 09/11/2013 12:44 PM, 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
>
>
> _______________________________________________
> Freeipa-devel mailing list
> Freeipa-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/freeipa-devel

I looked into the documentation effort and (ruby dependency discussion aside) I
don't have any major objections. I like how the generated pages look, and they
are intuitive and easy to navigate.

A couple of nitpicks:

1) There are some spelling mistakes (e.g. Apllication_controller)

2) Bulleted lists are not rendered nicely in the html output (see for example
the doc string for _base.Builder property 'string_mode'. I think a list needs to
look like this in the source code:

        /**
         * This is a list:
         *
         * - 'element1'
         * - 'element2'
         *
         */

as opposed to this:

        /**
         * This is a list:
         * - 'element1'
         * - 'element2'
         */

-- 
Regards,

Ana Krivokapic
Associate Software Engineer
FreeIPA team
Red Hat Inc.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20130916/05883767/attachment.htm>