struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Philip Luppens" <philip.lupp...@gmail.com>
Subject Examples and summaries in wiki via snippet plugin
Date Wed, 30 Jan 2008 09:12:29 GMT
Hi all,

I agree the snippet macro is quite useful to keep for example
attributes for tags in sync with the documentation in the wiki.

However, using that same technique to include a summary and/or
examples seems to be less fitting. It's often hard to write good and
well formatted samples in the javadoc code for display in the wiki
(esp. if you're dealing with XML tags and comments).

So, my question is: wouldn't it be better to keep the summary and
examples out of the javadocs and just put them in the wiki directly ?
I often find myself browsing the wiki to resolve some comments about
code samples having typoes(sp?) or display problems, and because I
don't have regular access to the struts svn because of my work, I
cannot make some quick adjustments (and neither can non-committers).
Creating (good-looking, well documented) examples is a lot easier in
confluence than it is in javadoc.

(Note: I am quite aware that we can simply throw out the snippet macro
line in a page and add the new example directly - I was simply
wondering if we shouldn't prefer it that way instead and move away
from the examples-in-javadoc)

Apologies if this has already been brought up before, my 2 cents,
comments welcome as always.

Phil

-- 
Software Architect - Hydrodesk
"Always code as if the guy who ends up maintaining your code will be a
violent psychopath who knows where you live." - John F. Woods

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org


Mime
View raw message