On Thu, Oct 23, 2008 at 1:03 AM, Dave Newton <[EMAIL PROTECTED]> wrote: > --- On Wed, 10/22/08, Philip Luppens wrote: >> Javadoc makes a very poor format for creating example code; > > Not in JavaDoc, as Java/JSP/FreeMarker/etc. and pulled in to the wiki via > snippets. That way they're examples that actually work. >
Not sure I'm following: what I meant are snippets of code and configuration being declared in the javadoc like this: /** * <!-- start snippet example --> * <foo> * <bar> * <!-- invalid example key --> * message['key'] = invalid; ... etc. Readability is less than optimal (esp. compared to the pure wiki variant), and I doubt this approach will keep the code in touch with the documentation. If there are many people looking at the examples, then problems will be spotted swiftly, and someone who filed a CLA can log in and make the changes, see the preview, and save the pages. If they're watching the page, they'll be notified, we can leave a comment, etc. If we want to correct a mistake in an example pulled from the repository, it goes like this (at least for me): Spot a comment on a page telling us that an example contains wrong or outdated code. Click to edit the page, discover the example is being pulled from the svn. If we have an IDE/svn client, fire it up, check out the source file, and make the change, commit it, go back to the page, verify it is looking correctly, sacrifce a goat to hope the snippet actually gets updated (I'm not sure it's seen as a new 'version' if a snippet gets changed and reloaded - can anyone verify ? - that would explain why some of the static pages are so outdated), and comment on the user comment that the code was changed. Ugh. I'll take a quick edit of the wiki page over that any time of the day. It looks better and it works faster. Note: I'm not talking about the inclusion of internal code and/or configuration files like 'struts-default.xml'. But those cases are very limited. Phil > Dave -- "We cannot change the cards we are dealt, just how we play the hand." - Randy Pausch --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
