RE: [xwiki-users] IDEA: API Documentation wiki
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]
Hi, Well my main issue is that the solution means a manual retrofitting of the best comments in the javadocs by commiters. The main benefit I see is not only to have comments but also to have the community directly work on the real javadoc. If we make the Wiki the original source for javadocs and write code which allows to update the SVN from the wiki content the I believe we have something more powerfull. As for supporting this for others APIs (and not only XWiki), well I think that looking at this issue in a more global way will create quite some work. As jdocs.org or other services once you tackle this problem you start doing a lot of different thing. Now once we have something working for XWiki we could propose it for other projects. Concernign links to other API docs, in the Wiki browser we could link to JDocs or javadocs.org sources. Ludovic THOMAS, BRIAN M (SBCSI) a écrit :
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]
------------------------------------------------------------------------
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
-- Ludovic Dubost XPertNet: http://www.xpertnet.fr/ Blog: http://www.ludovic.org/blog/ XWiki: http://www.xwiki.com Skype: ldubost AIM: nvludo Yahoo: ludovic
Hi. Just some feedback from someone who is feeling their way through the API docs at the moment. I agree completely with your idea Ludovic, about updating the source with the best comment (maybe moderate the comments for inclusion, the highest is included) as an example. The reason being that whenever I am creating something in any language no matter what it is, the real world examples that have been supplied (eg mysql, java, php, groovy, velocity) by the developers/users are the ones that point out the "gotchas". As I learn something new, I have been adding it to the wiki (either mine or xwiki.org) to try and save someone the hours of experimentation. So are you thinking that the javadoc of the SVN source is created (maybe nightly) and used as content to the equivalent page in the wiki. Then the comments attached to that page are moderated. The highest moderated comment/example is committed as a patch to the SVN source automatically (maybe a simple replace of a designated area near the method that will be picked up in the javadoc next time it is generated). That way you get the best of both worlds. Excellent. I love it. How can we help? Cheers, Mark On Fri, 2006-03-17 at 01:10 +0100, Ludovic Dubost wrote:
Hi,
Well my main issue is that the solution means a manual retrofitting of the best comments in the javadocs by commiters. The main benefit I see is not only to have comments but also to have the community directly work on the real javadoc. If we make the Wiki the original source for javadocs and write code which allows to update the SVN from the wiki content the I believe we have something more powerfull.
As for supporting this for others APIs (and not only XWiki), well I think that looking at this issue in a more global way will create quite some work. As jdocs.org or other services once you tackle this problem you start doing a lot of different thing. Now once we have something working for XWiki we could propose it for other projects.
Concernign links to other API docs, in the Wiki browser we could link to JDocs or javadocs.org sources.
Ludovic
THOMAS, BRIAN M (SBCSI) a écrit :
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]
------------------------------------------------------------------------
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
plain text document attachment (message-footer.txt) -- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws -- Mark Robinson Regional Clarity Project Manager (HK & AU)
TNT Freight Managment (Australia) Limited TNT Freight Managment (Hong Kong) Limited 3rd floor, Two Harbourfront, 18-22 Tak Fung Street, Hung Hom, Kowloon, Hong Kong Tel: +852 26213688 (ext. 374) Mob: +852 90335711 Em : [email protected] Web: http://www.tntfreight.com
participants (3)
-
Ludovic Dubost -
Mark Robinson -
THOMAS, BRIAN M (SBCSI)