You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@myfaces.apache.org by Leonardo Uribe <lu...@gmail.com> on 2008/07/01 07:08:06 UTC
Re: [myfaces-builder-plugin] generate site files describing component, like maven-tagdoc-plugin
On Fri, Jun 27, 2008 at 11:41 AM, Leonardo Uribe <lu...@gmail.com> wrote:
>
>
> On Fri, Jun 27, 2008 at 2:59 AM, simon.kitching@chello.at <
> simon.kitching@chello.at> wrote:
>
>> Man, I really hate top-posting. My first reply was in top-posting style
>> because the first reply to this thread was top-posted. But now the styles
>> are mixed, and this thread is rather painful to follow. My reply is
>> somewhere in the middle here....
>>
>> I really do think that consistently posting *under* the text that is being
>> replied to leads to threads that are *much* easier to read.
>>
>>
> Ok, I understand the error. I'll try to do not do if anymore.
>
>
>>
>> Leonardo Uribe schrieb:
>>
>>>
>>>
>>> On Fri, Jun 27, 2008 at 1:53 AM, simon.kitching@chello.at <mailto:
>>> simon.kitching@chello.at> <simon.kitching@chello.at <mailto:
>>> simon.kitching@chello.at>> wrote:
>>>
>>> Do you mean pages like this?
>>> http://myfaces.apache.org/tomahawk/popup.html
>>>
>>>
>>> Yes. Each time we want to upgrade some component, we have to write this
>>> part manually.
>>>
>>>
>>> I'm not sure that the "syntax" section here is particularly
>>> useful. That information is available in the taglib docs; no point
>>> in repeating it. And the API section isn't terribly useful; maybe
>>> for people who want to customise a component it makes it easier to
>>> find the real component class, but that isn't often.
>>>
>>> The "description" field could be copied I suppose; that would be
>>> mildly useful.
>>>
>>> But the rest is all hand-written.
>>>
>>> Or did you mean something else?
>>>
>>>
>>> Trinidad has an generated Tag library information (using
>>> maven-tagdoc-plugin) here:
>>>
>>> http://myfaces.apache.org/trinidad/trinidad-api/tagdoc.html
>>>
>>> When you navigate through this, you can find a lot more info than on its
>>> java taglibdoc.
>>>
>>> One question is why have a extended doc on tomahawk (see
>>> http://myfaces.apache.org/tomahawk/extendedDocs.html) link, if all
>>> necessary info is on its tld (or could be added here).
>>>
>>> We have 3 alternatives:
>>>
>>> 1. Remove extended doc pages and do and merge the info on the description
>>> field of each component (so this is available on its taglibdoc).
>>> 2. Remove extended doc pages and apply Trinidad solution: a custom report
>>> goal that generate all the info.
>>> 3. Do nothing and live with the fact of maintain 70 or more pages that
>>> say a little bit more than on the taglibdoc.
>>>
>>> Suggestions?
>>>
>>
>> It looks to me like the trinidad report is a complete replacement for the
>> standard taglib report, containing all the info of the existing taglib
>> reports plus more. And they look nicer too. So I'd be happy to see us use
>> the same maven report plugin that trinidad does, instead of the current
>> taglib plugin. And ditch the "extended doc" pages.
>>
>
> That's the point. The idea is follow a pattern like when generating a
> config file. There exists a xml base file, a template and the result is the
> merge the two of them plus the info on the metadata.
>
> We can add additional info as params (to save the xml base file if is
> possible) of the model trying to not cause unnecessary pollution.
>
>
>>
>> I'm not sure that (1) is possible. The existing "extended doc" pages
>> contain screenshots, html tables, etc. that just cannot be represented as
>> javadoc AFAIK. So there would be no way to enhance the javadoc on components
>> in a way that would generate anything like the existing "extended doc" or
>> the trinidad report. I presume the trinidad report merges in hand-written
>> html that can contain stuff like images and stuff?,
>>
>
> I have not seen this in deep (there are not screenshots on the doc). The
> plugin does not suggest any merge.
>
>
>> Regards,
>> Simon
>>
>>
>>>
>>> Regards, Simon
>>>
>>>
>>> Leonardo Uribe schrieb:
>>>
>>> The idea could be use velocity templates like everything.
>>>
>>> On Thu, Jun 26, 2008 at 10:38 PM, Leonardo Uribe
>>> <lu4242@gmail.com <ma...@gmail.com>
>>> <mailto:lu4242@gmail.com <ma...@gmail.com>>> wrote:
>>>
>>> Hi
>>>
>>> It could be good if we could generate the site files describing
>>> each component using myfaces-builder-plugin (generate from
>>> myfaces-metadata.xml instead from faces-config.xml).
>>>
>>> It's a waste of effort have to maintain this files. If we
>>> do this,
>>> we make easier move components from sandbox to tomahawk.
>>>
>>> I'll try it and see what happens.
>>>
>>> Suggestions are welcome.
>>>
>>> regards
>>>
>>> Leonardo Uribe
>>>
>>>
>>>
>>>
>>>
>>
>
Hi
I have committed myfaces-builder-plugin:tagdoc-index and tagdoc-content
goals and apply it to tomahawk core. Now the objective is apply it to
sandbox. By that reason, the files related to extended docs about components
will be deleted, because this plugin generate a more complete info.
regards
Leonardo Uribe
Re: [myfaces-builder-plugin] generate site files describing component, like maven-tagdoc-plugin
Posted by Leonardo Uribe <lu...@gmail.com>.
On Tue, Jul 1, 2008 at 3:03 AM, simon.kitching@chello.at <
simon.kitching@chello.at> wrote:
> Leonardo Uribe schrieb:
>
>>
>>
>>
>> I'm not sure that (1) is possible. The existing "extended doc"
>> pages contain screenshots, html tables, etc. that just cannot
>> be represented as javadoc AFAIK. So there would be no way to
>> enhance the javadoc on components in a way that would generate
>> anything like the existing "extended doc" or the trinidad
>> report. I presume the trinidad report merges in hand-written
>> html that can contain stuff like images and stuff?,
>>
>>
>> I have not seen this in deep (there are not screenshots on the
>> doc). The plugin does not suggest any merge.
>>
>> By "hand-written" and "merge" I meant that there needed to be something
> other than the javadocs. And there is: these "-base.xml" files get merged
> with the model data, and they contain <screenshot> tags etc which provide
> info that just cannot be embedded in the javadoc. I was expecting real html
> in the templates rather than a custom format, but the current template
> format is fine.
>
> BTW, how similar is this to the way trinidad generates its docs? Identical,
> or somewhat modified? Is the "template" file format the same? (just
> curious...)
>
The idea was taken from myfaces-tagdoc-plugin (in fact first I did a
conversion and then enhance it). This plugin generate xdoc files to the
directory target/generated-site/xdoc. Maven site plugin then takes all files
from here and process it to generate proper html files. Then generate an
index using the maven reporting api and doxia.
The original myfaces-tagdoc-plugin is non very flexible. You cannot add
content to the generated files, so all the info should be in build project
(in other word on the faces-config.xml file). Also the template is embedded
on the code (like myfaces-faces-plugin). So I use the same pattern for
generate config files (use a -base.xml file that its children inside <body>
section are added to the generated file) using again velocity. This allow us
to add whatever we want(images, additional info...) without alter the model
(I want to add a param to @JSFProperty called validValues="list,table", and
event annotations but later).
The drawback is that maven site plugin invokes velocity, so I had to
separate the original goal in two (tagdoc-content and tagdoc-index), to
avoid a class loader problem.
The objective right now is create -base.xml files per each component and
move the documentation available before on extended docs.
After we finish this task the last is remove old files and add the reference
to the tagdoc on the index.
>
>>
>> I have committed myfaces-builder-plugin:tagdoc-index and tagdoc-content
>> goals and apply it to tomahawk core. Now the objective is apply it to
>> sandbox. By that reason, the files related to extended docs about components
>> will be deleted, because this plugin generate a more complete info.
>>
> +1.
>
> This all looks great.
>
> Just two minor comments:
>
> /**
>> + * Triggers a standard dojo baseScriptUri as defined by the
>> + * <a href="http://dojotoolkit.org/">Dojo Toolkit</a>
>> + * <br />
>> + * <br />
>> + * Allows the alteration of the dojo loading root path
>> + * used by require.
>> + *
>>
>
> I don't much like <br/> in html at all, and certainly not two of them
> together. It doesn't make any semantic sense, and creates really ugly
> output. IMO, a paragraph tag is the right thing to use rather than
> linebreak. I would suggest *not* wrapping the first sentence in a paragraph
> tag; it isn't needed and looks ugly, but this works:
> /**
> * Triggers a standard dojo baseScriptUri etc etc.
> * <p>
> * Allows the alteration of the dojo ...
> * </p>
>
>
> And the first sentence of any javadoc block should be a stand-alone
> summary. The first sentence of this doesn't make sense as a summary:
>
>
> /**
> + * The MyFacesDataTable extends the standard JSF DataTable by two
> + * important features:
> + * <br/>
>
>
> Not worth fixing at the moment, but maybe worth keeping in mind when making
> future changes..
>
> Regards,
> Simon
>
>
Re: [myfaces-builder-plugin] generate site files describing component,
like maven-tagdoc-plugin
Posted by "simon.kitching@chello.at" <si...@chello.at>.
Leonardo Uribe schrieb:
>
>
>
> I'm not sure that (1) is possible. The existing "extended doc"
> pages contain screenshots, html tables, etc. that just cannot
> be represented as javadoc AFAIK. So there would be no way to
> enhance the javadoc on components in a way that would generate
> anything like the existing "extended doc" or the trinidad
> report. I presume the trinidad report merges in hand-written
> html that can contain stuff like images and stuff?,
>
>
> I have not seen this in deep (there are not screenshots on the
> doc). The plugin does not suggest any merge.
>
By "hand-written" and "merge" I meant that there needed to be something
other than the javadocs. And there is: these "-base.xml" files get
merged with the model data, and they contain <screenshot> tags etc which
provide info that just cannot be embedded in the javadoc. I was
expecting real html in the templates rather than a custom format, but
the current template format is fine.
BTW, how similar is this to the way trinidad generates its docs?
Identical, or somewhat modified? Is the "template" file format the same?
(just curious...)
>
>
> I have committed myfaces-builder-plugin:tagdoc-index and
> tagdoc-content goals and apply it to tomahawk core. Now the objective
> is apply it to sandbox. By that reason, the files related to extended
> docs about components will be deleted, because this plugin generate a
> more complete info.
+1.
This all looks great.
Just two minor comments:
> /**
> + * Triggers a standard dojo baseScriptUri as defined by the
> + * <a href="http://dojotoolkit.org/">Dojo Toolkit</a>
> + * <br />
> + * <br />
> + * Allows the alteration of the dojo loading root path
> + * used by require.
> + *
>
I don't much like <br/> in html at all, and certainly not two of them
together. It doesn't make any semantic sense, and creates really ugly
output. IMO, a paragraph tag is the right thing to use rather than
linebreak. I would suggest *not* wrapping the first sentence in a
paragraph tag; it isn't needed and looks ugly, but this works:
/**
* Triggers a standard dojo baseScriptUri etc etc.
* <p>
* Allows the alteration of the dojo ...
* </p>
And the first sentence of any javadoc block should be a stand-alone
summary. The first sentence of this doesn't make sense as a summary:
/**
+ * The MyFacesDataTable extends the standard JSF DataTable by two
+ * important features:
+ * <br/>
Not worth fixing at the moment, but maybe worth keeping in mind when
making future changes..
Regards,
Simon