myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jakob Korherr <jakob.korh...@gmail.com>
Subject Re: javascript docs
Date Tue, 26 Jul 2011 08:52:06 GMT
Hi,

IMO we can put this stuff into myfaces-builder-plugin (maybe re-use
some code from already existing open source plugins).

Furthermore, if packaging is a problem, we can use the assembly-plugin
to generate a jar file and attach it as a maven-artifact to the build
lifecycle!

Regards,
Jakob

2011/7/26 Leonardo Uribe <lu4242@gmail.com>:
> Hi
>
> The problem about use those plugins is they are not available on
> apache maven repo, so we had to link to some unknown repo. I don't
> know if this could be problematic, maybe in practice we have to
> repackage some code there and put as a maven plugin, knowing that the
> code is maintained somewhere else and we have to synch it from time to
> time, to ensure our code will build the jsdoc. Sound reasonable in any
> case.
>
> regards,
>
> Leonardo Uribe
>
> 2011/7/25 Werner Punz <werner.punz@gmail.com>:
>> 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
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>>
>>>
>>
>>
>>
>



-- 
Jakob Korherr

blog: http://www.jakobk.com
twitter: http://twitter.com/jakobkorherr
work: http://www.irian.at

Mime
View raw message