myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Leonardo Uribe" <lu4...@gmail.com>
Subject Re: [myfaces-builder-plugin] generate site files describing component, like maven-tagdoc-plugin
Date Tue, 01 Jul 2008 19:26:59 GMT
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
>
>

Mime
View raw message