myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Werner Punz <werner.p...@gmail.com>
Subject Re: javascript docs
Date Mon, 25 Jul 2011 23:01:17 GMT
http://dev.abiss.gr/mvn-jstools/index.html

and a bunch of others :-)


Am 26.07.11 00:57, schrieb Werner Punz:
> http://code.google.com/p/jsdoctk-plugin/
>
>
> Am 26.07.11 00:29, schrieb Leonardo Uribe:
>> 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