+1 My suggestion would be to retain technically complete but minimalistic Javadocs, and link from the Javadoc to the wikidoc (and also link from the wikidoc to the Javadoc).
The underlying goal is to single-source the documentation, and avoid cutting-and-pasting between assets. One way to single-source is to use something like a snippet macro, but I think bi-directional linking can work as well. -Ted. On Jan 30, 2008 3:12 AM, Philip Luppens <[EMAIL PROTECTED]> wrote: > 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: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > -- HTH, Ted http://husted.com/ted/blog/ --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
