myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "simon.kitching@chello.at" <simon.kitch...@chello.at>
Subject Re: [myfaces-builder-plugin] generate site files describing component, like maven-tagdoc-plugin
Date Tue, 01 Jul 2008 08:03:57 GMT
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


Mime
View raw message