Ok guys after working until midnight yesterday and a few hours of work
today I have a preliminary version of our docs online
http://people.apache.org/~werpu/jsdoc/
(Note I only annotated classes which are in production as well, so no
ext classes and no debugging classes for now.
So far jsdoc has scaled pretty well, the docs are not 100% ideal but
good enough and the annotations are very flexible, you can bend them
pretty well to our impl structures.
I have to do some further testing on the scripts (I did some smaller
code cleanups while documenting the most important classes thoroughly)
so my apologies that the commit of the newly annotated classes will not
happen this week anymore.
After that I will start to investigate on how we can get this into
maven, to get the doc generation automated.
It will probably end up like Jakob proposed that we will take one of the
existing plugins and pull it into our build tools.
Werner
Am 26.07.11 10:52, schrieb Jakob Korherr:
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<[email protected]>:
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<[email protected]>:
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<[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
