6 Feb
2008
6 Feb
'08
6:22 p.m.
Vincent Massol wrote:
Hi Sergiu,
On Feb 6, 2008, at 5:42 PM, Sergiu Dumitriu wrote:
You should instead *insist* that people document the code before
releasing. A plugin is not like the whole XWiki class, so it should be
easy to document.
Even more, people responsible for a plugin should ensure their code
passes the checkstyle before releasing. For a reasonable plugin that
shouldn't be so hard or time consuming.
Hi,
I think it would be better to publish the plugin API javadoc on the
XWiki site, instead of manually putting some pseudo java interface
in a
{code} block. We do the same for the platform-core, by uploading the
generated javadoc jar and using the zipexplorer plugin to show the
index
page.
I agree.
Several things:
1) This is not meant to be the javadoc. It's simply because lots (if
not the great majority) ofl XWiki developers don't care about
documentation and they never bother to create it. Thus I'm finding
myself forced to document it for them when the release time comes. And
since I don't have 3 days to document everyone's else code, I've just
quickly copy-pasted some interfaces to ensure we've got something to
document... In real I'd like to have a short tutorial on the
capabilities of the plugin, some examples about using it, etc. 2) I agree about the javadoc. We need this. Right now
it's too much of
a pain to do so we need to do some automation before this can become a
real way of doing it. In particular I think we need to write some
maven plugin that will do several things:
A) deploy the plugin in the download section
B) deploy the javadoc and link it
C) Create a blog post to announce the release
etc
Yes, you mentioned this another time (don't know if to me in private, or
on the list), and I completely agree. My only concern was security (the
need for a username/password to be present somewhere in the plugin
code). But this was my mistake, as I was trying to imagine a completely
automated build. We should just require some -Dpassword, -Dusername
parameters or ask them from the command line, like the release plugin
asks for the released and next versions.
Sergiu