RE: [xwiki-users] IDEA: API Documentation wiki
by THOMAS, BRIAN M (SBCSI)
Ludovic,
Thanks for your enthusiastic (and quick!) response. It's certainly a
start, though it will only work for XWiki's documentation. That's okay,
if it turns out to be quicker and easier to drive it from the XWiki
database; solving the immediate problem is the most important for the
moment.
But it would be much more generally useful if you could just point a
template at any arbitrary javadoc site, with a CVS or other source link
optional, and at each place where javadoc comments would be displayed by
the standard doclet, insert an HTML element that included the wiki
document, if it existed, or a create link if it didn't. Simple style
options could let the user choose whether to append or overlay the wiki
page on existing comments, or (possibly) even to embed them,
highlighted. In this way, the hand-copying of the original javadoc
comments would be unnecessary, and it might even provide a nice easy
means for the owners of the sources to retrofit the better ones into the
repository.
Whichever way is easier (and/or faster) to do it for Xwiki will be the
best for now; I was just wondering if it would be any harder to craft
the more general solution, and you might get more helpers than for
something that only works for one set of APIs.
BTW, I have this problem often, as do all the males in my family:
because my surname, Thomas, is also a very common first name (probably
more so than as a surname), I'm often referred to by it, or by "Tom".
No offense taken, of course; I have corrected it, and made what I
thought would be a link to my profile page, but the create link appeared
instead. Does xwiki.org not automatically create a profile page for
every user? I followed it to get a permission-denied page, so maybe I
just can't edit it, but my name appears as a normal link in the "Hello"
section. I thought that if a page existed, the create link wouldn't
appear...
brain[sic]
