myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leonardo Uribe <lu4...@gmail.com>
Subject Re: javascript docs
Date Mon, 25 Jul 2011 22:29:45 GMT
Hi

The problem to use jsdoc is there is no maven plugin that executes it.
For now we only have the ant task solution. Things are getting messy
when you try to setup other plugins like maven jar plugin, because
there is no way to define the ordering execution of the plugins
without create a custom maven lifecycle. So, at the end we need to
create a maven plugin for this one, if we want things like package
documentation inside a jar or add as a report for our site.

It is true we'll have some "overhead" anyway, because we had to
maintain something else. Now, in the context of jsf, we want a
javascript documentation for maintain our custom jsf javascript API
and utilities. It could be good to integrate it in some way with
myfaces-builder-plugin and have some annotations. This could be
useful, for generate the tag documentation. For example, see this
link:

http://myfaces.apache.org/tomahawk-project/tomahawk20/tagdoc/t_inputText.html

Look you can click on component/renderer classes and see the generated
javadoc. We could add some links to the javascript files used by that
component. Or if we go beyond, we can create some annotations to be
scanned on the javascript files associated with the component.

At the end, the priority is get a decent javascript documentation that
can be added to our site and generate -jsdoc.jar files to attach to
myfaces assemblies and on maven repo. So if we can do it with jsdoc,
well, that's ok. But in my personal opinion, in the long term a
"custom javascript documentation" solution could be more appropiate to
our needs, and if we have to create a custom maven plugin to solve
this one anyway, it is worth a shot.

Leonardo

2011/7/25 Werner Punz <werner.punz@gmail.com>:
> Hi the jsdoc is just more or less a command line tool (actually a jar)
> I have yet to investigate the links to maven, Leo did some work there.
> I am personally not very much in favor of running our own tool as long as we
> can get away with jsdoc. This is another codebase to maintain which I want
> to try to avoid. But if someone wants to come up with the work and wants to
> build our own custom doc solution, go ahead.
> I am in favor of any solution, jsdoc just looked sane to me, because it is
> use widely and maintained and can be leveraged to our codebase as it seems,
> with a set of meta annotations.
>
>
> Werner
>
> Am 25.07.11 19:30, schrieb Bernd Bohmann:
>>
>> Hello Werner,
>>
>> is the jsdoc produced by a maven plugin? Or is the output somewhere in
>> the target directory? If yes, it should be not a problem to use the
>> jar plugin to package the js docs.
>>
>> Regards
>>
>> Bernd
>>
>> On Mon, Jul 25, 2011 at 7:00 PM, Werner Punz<werner.punz@gmail.com>
>>  wrote:
>>>
>>> I only can guess here since I dont know if jsdoc can generate jars, but
>>> my
>>> assumption is that we have to roll our own custom plugin.
>>> This is still less work than to write our own javascript doc parser
>>> or to adjust an existing codebase.
>>>
>>> Werner
>>>
>>>
>>> Am 25.07.11 18:26, schrieb Leonardo Uribe:
>>>>
>>>> Hi Werner
>>>>
>>>> Yes, I was expecting that. The problem is how to generate an artifact
>>>> that should be attached to the pom.xml, so it is deployed on maven
>>>> repo when is generated, without write a custom plugin.
>>>>
>>>> regards,
>>>>
>>>> Leonardo
>>>>
>>>> 2011/7/25 Werner Punz<werner.punz@gmail.com>:
>>>>>
>>>>> Hi Leo no just the plain html docs.
>>>>> I have to check if we can generate a jar out of it, if not we probably
>>>>> have to jar the stuff ourselves.
>>>>>
>>>>>
>>>>>
>>>>> Werner
>>>>>
>>>>>
>>>>> Am 25.07.11 18:20, schrieb Leonardo Uribe:
>>>>>>
>>>>>> Hi Werner
>>>>>>
>>>>>> Does this strategy generates a .jar?
>>>>>>
>>>>>> regards,
>>>>>>
>>>>>> Leonardo Uribe
>>>>>>
>>>>>> 2011/7/25 Werner Punz<werner.punz@gmail.com>:
>>>>>>>
>>>>>>> Ok I have basically all patterns working, please revisit the
link,
>>>>>>> you
>>>>>>> can
>>>>>>> see now the api, the runtime class (basically a namespace with
a set
>>>>>>> of
>>>>>>> functions)
>>>>>>> and the _Lang.js class, a singleton delegate which delegates
the
>>>>>>> namespace.
>>>>>>> The normal classes now should be no problem as well since they
use
>>>>>>> the same doc mechanics as the singleton objects.
>>>>>>>
>>>>>>> Again here is the link
>>>>>>>
>>>>>>> http://people.apache.org/~werpu/jsdoc/symbols/jsf.html
>>>>>>>
>>>>>>> Which means, I will rework the scripts first to allow jsdoc to
>>>>>>> compile
>>>>>>> them
>>>>>>> properly and then once done, I will integrate jsdoc properly
into our
>>>>>>> build
>>>>>>> system.
>>>>>>>
>>>>>>>
>>>>>>> Werner
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Am 25.07.11 16:36, schrieb Werner Punz:
>>>>>>>>
>>>>>>>> Actually I am working on the impl classes so far it looks
like I can
>>>>>>>> pull it off the _Runtime.js can definitely be documented
via jsdoc.
>>>>>>>> The other classes which are more OO probably also can be
mapped into
>>>>>>>> our
>>>>>>>> jsdocs.
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> Am 25.07.11 15:35, schrieb Jakob Korherr:
>>>>>>>>>
>>>>>>>>> Very nice. Great job, Werner!
>>>>>>>>>
>>>>>>>>> Regards,
>>>>>>>>> Jakob
>>>>>>>>>
>>>>>>>>> 2011/7/25 Werner Punz<werner.punz@gmail.com>:
>>>>>>>>>>
>>>>>>>>>> Hi everyone, I have started this week to work on
the javascript
>>>>>>>>>> documentation issues, so far I can cover our API
classes pretty
>>>>>>>>>> well
>>>>>>>>>> with
>>>>>>>>>> jsdoc. Only one minor code modification was needed
to get it up
>>>>>>>>>> and
>>>>>>>>>> running.
>>>>>>>>>>
>>>>>>>>>> Here is a first rough result by using jsdoc on the
API section:
>>>>>>>>>>
>>>>>>>>>> http://people.apache.org/~werpu/jsdoc/symbols/jsf.html
>>>>>>>>>>
>>>>>>>>>> Since my first goal simply was to get the api docs
out I will
>>>>>>>>>> merge
>>>>>>>>>> this
>>>>>>>>>> into our maven build and do the code adjustements
as needed.
>>>>>>>>>> To get jsdocs for the impl is a nice to have but
not vital, since
>>>>>>>>>> the
>>>>>>>>>> impl
>>>>>>>>>> classes should not be used anyway by the users.
>>>>>>>>>>
>>>>>>>>>> Werner
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>>
>>>
>>
>
>
>

Mime
View raw message