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<[email protected]>:
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<[email protected]>
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<[email protected]>:
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<[email protected]>:
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<[email protected]>:
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
