[xwiki-devs] Plugin API on code.xwiki.org
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. Sergiu
Hi Sergiu, On Feb 6, 2008, at 5:42 PM, Sergiu Dumitriu wrote:
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 Thanks -Vincent
Vincent Massol wrote:
Hi Sergiu,
On Feb 6, 2008, at 5:42 PM, Sergiu Dumitriu wrote:
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.
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.
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
participants (2)
-
Sergiu Dumitriu -
Vincent Massol