17 Mar
2006
17 Mar
'06
2:47 a.m.
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 :
--
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 : mark.robinson(a)hk.tntfreight.com
Web: http://www.tntfreight.com
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 xwiki-users(a)objectweb.org mailing list.
To unsubscribe: mailto:xwiki-users-unsubscribe@objectweb.org
For general help: mailto:sympa@objectweb.org?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 xwiki-users(a)objectweb.org mailing list.
To unsubscribe: mailto:xwiki-users-unsubscribe@objectweb.org
For general help: mailto:sympa@objectweb.org?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws