You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Bernhard Huber <be...@a1.net> on 2002/01/29 02:32:22 UTC
Reference Doc From Java Sources [Was Check Source]
Hi,
as noted by david there were some js problems, i removed the js refs
from the sample pages,
so a second try trigger some discussion about more accurate reference
documentation.
I try to summarize what I have done, i make a distro available under
http://members.a1.net/berni_huber/ref-docs/index.html .
My idea was not to replace javadoc documentation, but to help writing
the sitemap, avoiding to go to the java source code,
and to avoid writing too much explicit documentation which is never
uptodate with the java source code.
That's the whole indention.
Defined cocoon:tags :
@cocoon:name {name} name is sitemap name of the sitemap componented
implemented by this class
Proposed cocoon:tags:
@cocoon:deprecated [yes|no] Used for documenting deprectated sitemap
components.
More cocoon:tags:
@cocoon:optional [yes|no] describing if it is optional
@cocoon:core [yes|no] describing if its core
@cocoon:input-dtd for transformers describe the expected input
xml-document-type
@cocoon:output-dtd for transformers, and generators describe the
expected xml-document-type produced.
@cocoon:objectModel ? describe what is put into the objectmodel map.
...
I'm not quite sure about how detailed the @cocoon: tags should be....
bye bernhard
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Reference Doc From Java Sources [Was Check Source]
Posted by Stefano Mazzocchi <st...@apache.org>.
Sylvain Wallez wrote:
>
> Stefano Mazzocchi wrote:
>
> <snip/>
>
> >I'm going to spend some time taking a good look at your doclet today
> >and to the other doclet implementations available.
> >
> Do you know xdoclet at http://xdoclet.sourceforge.net/ ?
I just took a look at it (along with the DBDoclet which outputs docbook)
and I think that using Berni's work with Velocity is a *much* better
alternative.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Reference Doc From Java Sources [Was Check Source]
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Stefano Mazzocchi wrote:
<snip/>
>I'm going to spend some time taking a good look at your doclet today
>and to the other doclet implementations available.
>
Do you know xdoclet at http://xdoclet.sourceforge.net/ ?
Sylvain
--
Sylvain Wallez
Anyware Technologies - http://www.anyware-tech.com
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Reference Doc From Java Sources [Was Check Source]
Posted by Stefano Mazzocchi <st...@apache.org>.
Bernhard Huber wrote:
> >But the fact that we use javadocs syntax and javadoc tools might be
> >wrong!
> >
> >Now, I see two possible syntaxes:
> >
> >1) turn javadoc tag into namespaced ones (might becoming a black art)
> >
> >
> >2) write our own 'special-comment' with nested XML documentation
> >
> > /*?
> > <doc:doc xmlns:doc='...'>
> > ...
> > </doc>
> > ?*/
> >
> No I don't like 2), this will make it impossible to use the doclet API!
> Doclet API won't give you access to that comments, AFAIK.
Good point.
> What about, putting the complete XML to a single javadoc tag, like this:
>
> /** My one sentence description
> * @namespace:cocoon http://apache.org/cocoon/2.0/
> * @cocoon:doc <doc:doc xmlns:doc='...'>
> * <doc:head>bla, bla</doc:head>
> * <doc:body>bla, bla</doc:body>
> * </doc:doc>
> */
>
> I think it's not funny writing xml documentation in the java comment.
> If the number of javadoc tags is small, and clear, I think it is better
> than writing xml in the comment.
Completely agreed.
> Writing xml in the comment could be painful for programmers, and might
> be simply ignored by lazy programmers.
> Keep in mind that programmers/developers are supposed to write the
> documentation!
Absolutely. Javadocs are a pain by itself, we should make it as simple
as possible to add features to this system.
> >
> >
> >Another choice is the tool:
> >
> >1) write a tool on our own
> >
> >2) write a doclet
> >
> >The second option is nicer if the output is completely XML-ized!
> >
> > <javadoc:class xmlns:javadoc="....">
> > <doc:doc xmlns:doc='...'>
> > ...
> > </doc>
> > <javadoc:method ..../>
> > <javadoc:variable ../>
> > </javadoc>
> >and so on.
> >
> >*this* would be incredibly cool, since it would give us the ability to
> >'refactor' and aggregate code documentation easily from an XML-based
> >publishing framework.
> >
> >
> >
> >So, using Velocity is cool, but it's somewhat limited (unless you want
> >to write a java parser in Velocity :) javadoc already comes with a java
> >parser... but I never wrote a doclet so I'm not sure how that goes (but
> >we already have a javadoc DTD that suits our needs!)
> >
> Note: The sample code I wrote is a doclet, I used Velocity only for
> generating the xml documents.
> Using Velocity was driven by:
> * Be flexible in generating what kind of xml document
> * Be flexible in accessing object provided by the doclet API.
>
> Thus the Velocity templates are generators.
> Thus the Velocity templates are transformers.
>
> There is no need to implement a java parser in Velocity.
>
> Short note about doclet: You have an API, providing you with beans about
> all parsed classes, packages, methods, members.
> Thus you can access the full name of a class like: 'classDoc.fullName()'.
>
> Thus my suggestion:
> 1) Programmers keep writing java source documentation.
> 2) Programmers do not write xml, but javadoc tags.
> 3) A project may define special tags, and a namespace
>
> 4) A doclet generates xml documents from the java documentation.
> 5) Using the default doclet of javadoc still provides valid, and
> sensefull html documentation.
>
> 6) Using VelocityDoclet you have to write templates which generates xml
> documents.
> 7) You may want write several "families" of templates/doclets to
> generate different xml documents from the java sources.
> So you can generate xml documents having same info as today
> html-javadocumentation, ignoring project specific tags.
> You can generate xml documents taking only some classes into account,
> and some project specific tags for having project specific reference
> documentation, ignoring method details.
Totally +1
I'm going to spend some time taking a good look at your doclet today and
to the other doclet implementations available.
Catcha l8r.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Reference Doc From Java Sources [Was Check Source]
Posted by Bernhard Huber <be...@a1.net>.
Hi,
>
>*this* is what we need: the ability to write our documentation with the
>code and the ability to factor it out and aggregate it coherently with
>our own.
>
yep.
>
>
>But the fact that we use javadocs syntax and javadoc tools might be
>wrong!
>
>Now, I see two possible syntaxes:
>
>1) turn javadoc tag into namespaced ones (might becoming a black art)
>
>
>2) write our own 'special-comment' with nested XML documentation
>
> /*?
> <doc:doc xmlns:doc='...'>
> ...
> </doc>
> ?*/
>
No I don't like 2), this will make it impossible to use the doclet API!
Doclet API won't give you access to that comments, AFAIK.
What about, putting the complete XML to a single javadoc tag, like this:
/** My one sentence description
* @namespace:cocoon http://apache.org/cocoon/2.0/
* @cocoon:doc <doc:doc xmlns:doc='...'>
* <doc:head>bla, bla</doc:head>
* <doc:body>bla, bla</doc:body>
* </doc:doc>
*/
I think it's not funny writing xml documentation in the java comment.
If the number of javadoc tags is small, and clear, I think it is better
than writing xml in the comment.
Writing xml in the comment could be painful for programmers, and might
be simply ignored by lazy programmers.
Keep in mind that programmers/developers are supposed to write the
documentation!
>
>
>Another choice is the tool:
>
>1) write a tool on our own
>
>2) write a doclet
>
>The second option is nicer if the output is completely XML-ized!
>
> <javadoc:class xmlns:javadoc="....">
> <doc:doc xmlns:doc='...'>
> ...
> </doc>
> <javadoc:method ..../>
> <javadoc:variable ../>
> </javadoc>
>and so on.
>
>*this* would be incredibly cool, since it would give us the ability to
>'refactor' and aggregate code documentation easily from an XML-based
>publishing framework.
>
>
>
>So, using Velocity is cool, but it's somewhat limited (unless you want
>to write a java parser in Velocity :) javadoc already comes with a java
>parser... but I never wrote a doclet so I'm not sure how that goes (but
>we already have a javadoc DTD that suits our needs!)
>
Note: The sample code I wrote is a doclet, I used Velocity only for
generating the xml documents.
Using Velocity was driven by:
* Be flexible in generating what kind of xml document
* Be flexible in accessing object provided by the doclet API.
Thus the Velocity templates are generators.
Thus the Velocity templates are transformers.
There is no need to implement a java parser in Velocity.
Short note about doclet: You have an API, providing you with beans about
all parsed classes, packages, methods, members.
Thus you can access the full name of a class like: 'classDoc.fullName()'.
Thus my suggestion:
1) Programmers keep writing java source documentation.
2) Programmers do not write xml, but javadoc tags.
3) A project may define special tags, and a namespace
4) A doclet generates xml documents from the java documentation.
5) Using the default doclet of javadoc still provides valid, and
sensefull html documentation.
6) Using VelocityDoclet you have to write templates which generates xml
documents.
7) You may want write several "families" of templates/doclets to
generate different xml documents from the java sources.
So you can generate xml documents having same info as today
html-javadocumentation, ignoring project specific tags.
You can generate xml documents taking only some classes into account,
and some project specific tags for having project specific reference
documentation, ignoring method details.
bye bernhard
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Reference Doc From Java Sources [Was Check Source]
Posted by Stefano Mazzocchi <st...@apache.org>.
Bernhard Huber wrote:
>
> Hi,
>
> >
> >What about coming out with a more-or-less standard extention to the
> >javadoc system and provide namespaces? for example:
> >
> > /**
> > * This is my comment.
> > *
> > * @namespace:cocoon http://apache.org/cocoon/2.0/
> > * @cocoon:deprecated no
> > * @namespace:xsp http://apache.org/xsp/1.0/
> > * @xsp:deprecated yes
> > */
> >
> >what do you think? might be FS but I think tag collisions will happen
> >frequently expecially if this system is moved to Ant or something like
> >that.
> >
> I have already forgotten abbrev FS.
Flexibility Syndrome.
> BTW, I think your suggestion makes a
> lot sense, and it's quite flexible.
exactly :) my question was: 'too much'?
> We may even predefine some namespaces, like
> @namespace:cocoon http://apache.org/cocoon/2.0/.
yes, as long as you leave the ability to be 'overruled' in the source
file.
> For the xsp I see no usage, but maybe I'm missing something.
Well, don't know, maybe it could be useful for automatic Taglib
documentation, to map methods and parameters to the taglib markup.
> For the non-sitemap-and-avalon-components-only let's introduce
> @namespace:avalon http://apache.org/avalon/4.1/ ?
Great.
> >
> >>More cocoon:tags:
> >>@cocoon:optional [yes|no] describing if it is optional
> >>@cocoon:core [yes|no] describing if its core
> >>
> >
> >If something is not core is optional, or is there something in between?
> >
> Yup: default, What's about, using "status", we may even add deprecated,...
> @cocoon:status [default|core|optional]
+1
> >
> >
> >>@cocoon:input-dtd for transformers describe the expected input
> >>xml-document-type
> >>@cocoon:output-dtd for transformers, and generators describe the
> >>expected xml-document-type produced.
> >>
> >
> >Nah, this doesn't work.
> >
> >XSLTTransformer: what are the input/output schemas?
> >XMLSerializers: what is the input schema?
> >
> >yes, some components know the output or the input (directory markup for
> >the directory generator, FO for PDFSerializer), but is this worth the
> >effort? pipelines can't be validated at authoring time anyway.
> >
> Yes, but imagine you want to use the directory generator, you must know
> the DTD of the xml generated,
> if you want to write the XSLT.
> I understand the concern, but using the generator you must know the DTD,
> so somewhere it should be documented anyway. Thus I suggested these
> javadoc tags. On the other hand it's only reference documentation.
Good point.
But let's make this DTD agnostic since in the future nobody will use
DTDs anymore: what about something like
@cocoon:input-schema
@cocoon:output-schema
?
> >>@cocoon:objectModel ? describe what is put into the objectmodel map.
> >>
> >
> >Hmmm, I think this is too code-level.
> >
> >What about things like in-out parameters [for actions, matchers,
> >selectors], or things like returned tokens... anything that can be
> >useful for sitemap authoring (probably even to assist an authoring tool)
> >
> Yes, that's a point.
> For example a try for a I18NTransformer documentation:
>
> /**
> * Internationalisation transformer; used to transform i18n markup into
> text based on a particular locale.
> *
>
> * @namespace:cocoon http://apache.org/cocoon/2.0/
>
> * @cocoon:name="i18n"
> * @cocoon:status="core"
> * @cocoon:config element-name="catalogue-name"
> * type="string"
> * description="base name of the message catalogue (<i>mandatory</i>)."
> * @cocoon:config element-name="catalog-location"
> * type="context-location"
> * description="location of the message catalogues (<i>mandatory</i>).
> * @cocoon:config element-name="untranslated-text"
> * type="string"
> * description="default text used for untranslated keys (default is
> 'untranslated-text').
> * @cocoon:config element-name="cache-at-startup"
> * type="true|false"
> * description="flag whether to cache messages at startup (false by
> default).
>
> * @cocoon:action http-request-parameter name="lang"
> description="defines the locale in the http request parameter"
> * type="{language}(_{country}(_{variant})?)?"
> * @cocoon:action http-session-parameter name="lang"
> *
> */
Uh, getting kinda verbose...
> Moreover what about the xconf parameters?
> For example XSLT processor allows the configuration parameters:
> use-store, incremental-processing
> Lets'define:
> @avalon:param name="incremental-processing"
> allowed-values="true|false"
> description="Turn 'incremental-processing' to true if you want a
> continous output"
yes, makes sense.
> Probably I have to reread the doclet documentation, there is some
> special tag procesing for Param tags,
> other wise we define to much tags, and it will become an art of its own
> writing that kind of documentation....
>
> Structurally I see some problems describing hierachical configuration
> this kind of flat javadoc tags.
I was thinking the same thing.
Even more: javadocs are very granular since they describe methods
classes and variables.... we just need to describe classes and we need
more nesting capabilities.
Are we sure javadocs is the tool we need for this?
> But perhaps we may check, if some mandatory tags are missing in the
> javadoc, and generate warnings.
>
> Implementation note:
> I think using Velocity is okay for that task, I read a note in the
> velocity mailing list, that someone used this kind of approach
> for generating EJB home, and interface java sources.
> The XDoclet may be more flexible, but I didn't managed to understand the
> structure....
The cool concept about javadocs is that they live with the code, but
allow documentation to be factored out (un-cross-cutted, for the AOP
oriented of you) (yes, I see documentation as an 'aspect' of the source
code)
*this* is what we need: the ability to write our documentation with the
code and the ability to factor it out and aggregate it coherently with
our own.
But the fact that we use javadocs syntax and javadoc tools might be
wrong!
Now, I see two possible syntaxes:
1) turn javadoc tag into namespaced ones (might becoming a black art)
2) write our own 'special-comment' with nested XML documentation
/*?
<doc:doc xmlns:doc='...'>
...
</doc>
?*/
Another choice is the tool:
1) write a tool on our own
2) write a doclet
The second option is nicer if the output is completely XML-ized!
<javadoc:class xmlns:javadoc="....">
<doc:doc xmlns:doc='...'>
...
</doc>
<javadoc:method ..../>
<javadoc:variable ../>
</javadoc>
and so on.
*this* would be incredibly cool, since it would give us the ability to
'refactor' and aggregate code documentation easily from an XML-based
publishing framework.
So, using Velocity is cool, but it's somewhat limited (unless you want
to write a java parser in Velocity :) javadoc already comes with a java
parser... but I never wrote a doclet so I'm not sure how that goes (but
we already have a javadoc DTD that suits our needs!)
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Reference Doc From Java Sources [Was Check Source]
Posted by Bernhard Huber <be...@a1.net>.
Hi,
>
>What about coming out with a more-or-less standard extention to the
>javadoc system and provide namespaces? for example:
>
> /**
> * This is my comment.
> *
> * @namespace:cocoon http://apache.org/cocoon/2.0/
> * @cocoon:deprecated no
> * @namespace:xsp http://apache.org/xsp/1.0/
> * @xsp:deprecated yes
> */
>
>what do you think? might be FS but I think tag collisions will happen
>frequently expecially if this system is moved to Ant or something like
>that.
>
I have already forgotten abbrev FS. BTW, I think your suggestion makes a
lot sense, and it's quite flexible.
We may even predefine some namespaces, like
@namespace:cocoon http://apache.org/cocoon/2.0/.
For the xsp I see no usage, but maybe I'm missing something.
For the non-sitemap-and-avalon-components-only let's introduce
@namespace:avalon http://apache.org/avalon/4.1/ ?
>
>>More cocoon:tags:
>>@cocoon:optional [yes|no] describing if it is optional
>>@cocoon:core [yes|no] describing if its core
>>
>
>If something is not core is optional, or is there something in between?
>
Yup: default, What's about, using "status", we may even add deprecated,...
@cocoon:status [default|core|optional]
>
>
>>@cocoon:input-dtd for transformers describe the expected input
>>xml-document-type
>>@cocoon:output-dtd for transformers, and generators describe the
>>expected xml-document-type produced.
>>
>
>Nah, this doesn't work.
>
>XSLTTransformer: what are the input/output schemas?
>XMLSerializers: what is the input schema?
>
>yes, some components know the output or the input (directory markup for
>the directory generator, FO for PDFSerializer), but is this worth the
>effort? pipelines can't be validated at authoring time anyway.
>
Yes, but imagine you want to use the directory generator, you must know
the DTD of the xml generated,
if you want to write the XSLT.
I understand the concern, but using the generator you must know the DTD,
so somewhere it should be documented anyway. Thus I suggested these
javadoc tags. On the other hand it's only reference documentation.
>>@cocoon:objectModel ? describe what is put into the objectmodel map.
>>
>
>Hmmm, I think this is too code-level.
>
>What about things like in-out parameters [for actions, matchers,
>selectors], or things like returned tokens... anything that can be
>useful for sitemap authoring (probably even to assist an authoring tool)
>
Yes, that's a point.
For example a try for a I18NTransformer documentation:
/**
* Internationalisation transformer; used to transform i18n markup into
text based on a particular locale.
*
* @namespace:cocoon http://apache.org/cocoon/2.0/
* @cocoon:name="i18n"
* @cocoon:status="core"
* @cocoon:config element-name="catalogue-name"
* type="string"
* description="base name of the message catalogue (<i>mandatory</i>)."
* @cocoon:config element-name="catalog-location"
* type="context-location"
* description="location of the message catalogues (<i>mandatory</i>).
* @cocoon:config element-name="untranslated-text"
* type="string"
* description="default text used for untranslated keys (default is
'untranslated-text').
* @cocoon:config element-name="cache-at-startup"
* type="true|false"
* description="flag whether to cache messages at startup (false by
default).
* @cocoon:action http-request-parameter name="lang"
description="defines the locale in the http request parameter"
* type="{language}(_{country}(_{variant})?)?"
* @cocoon:action http-session-parameter name="lang"
*
*/
Moreover what about the xconf parameters?
For example XSLT processor allows the configuration parameters:
use-store, incremental-processing
Lets'define:
@avalon:param name="incremental-processing"
allowed-values="true|false"
description="Turn 'incremental-processing' to true if you want a
continous output"
Probably I have to reread the doclet documentation, there is some
special tag procesing for Param tags,
other wise we define to much tags, and it will become an art of its own
writing that kind of documentation....
Structurally I see some problems describing hierachical configuration
this kind of flat javadoc tags.
But perhaps we may check, if some mandatory tags are missing in the
javadoc, and generate warnings.
Implementation note:
I think using Velocity is okay for that task, I read a note in the
velocity mailing list, that someone used this kind of approach
for generating EJB home, and interface java sources.
The XDoclet may be more flexible, but I didn't managed to understand the
structure....
bye bernhard
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Reference Doc From Java Sources [Was Check Source]
Posted by Stefano Mazzocchi <st...@apache.org>.
Bernhard Huber wrote:
>
> Hi,
>
> as noted by david there were some js problems, i removed the js refs
> from the sample pages,
> so a second try trigger some discussion about more accurate reference
> documentation.
>
> I try to summarize what I have done, i make a distro available under
> http://members.a1.net/berni_huber/ref-docs/index.html .
>
> My idea was not to replace javadoc documentation, but to help writing
> the sitemap, avoiding to go to the java source code,
> and to avoid writing too much explicit documentation which is never
> uptodate with the java source code.
I love it.
> That's the whole indention.
>
> Defined cocoon:tags :
> @cocoon:name {name} name is sitemap name of the sitemap componented
> implemented by this class
>
> Proposed cocoon:tags:
> @cocoon:deprecated [yes|no] Used for documenting deprectated sitemap
> components.
Hmmm, will this scale in the future?
What about coming out with a more-or-less standard extention to the
javadoc system and provide namespaces? for example:
/**
* This is my comment.
*
* @namespace:cocoon http://apache.org/cocoon/2.0/
* @cocoon:deprecated no
* @namespace:xsp http://apache.org/xsp/1.0/
* @xsp:deprecated yes
*/
what do you think? might be FS but I think tag collisions will happen
frequently expecially if this system is moved to Ant or something like
that.
> More cocoon:tags:
> @cocoon:optional [yes|no] describing if it is optional
> @cocoon:core [yes|no] describing if its core
If something is not core is optional, or is there something in between?
> @cocoon:input-dtd for transformers describe the expected input
> xml-document-type
> @cocoon:output-dtd for transformers, and generators describe the
> expected xml-document-type produced.
Nah, this doesn't work.
XSLTTransformer: what are the input/output schemas?
XMLSerializers: what is the input schema?
yes, some components know the output or the input (directory markup for
the directory generator, FO for PDFSerializer), but is this worth the
effort? pipelines can't be validated at authoring time anyway.
> @cocoon:objectModel ? describe what is put into the objectmodel map.
Hmmm, I think this is too code-level.
What about things like in-out parameters [for actions, matchers,
selectors], or things like returned tokens... anything that can be
useful for sitemap authoring (probably even to assist an authoring tool)
What do you people want from this?
You'd better speak now :)
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org