If snippets only came from the example applications I'd agree with you
about the benefit of it maintaining valid syntax but they don't. They
also come from Javadoc comments that have syntax problems.
I wasn't trying to say that Javadoc creates a user manual. I was saying
that it already documents the implementation of the source so we don't
need to do that again.
I think the stated policy of try to make everything a snippet just goes
too far. The snippet macro does have some use but shouldn't be the
preferred way to create documentation content.
Can we get a struts21 and struts20 prefix setup for the snippet macro?
Along with prefixes for the corresponding versions of XWork.
-Matthieu
Dave Newton wrote:
--- Chase <[EMAIL PROTECTED]> wrote:
By making the content of the documentation external
to the documentation it causes several problems.
It also solves several problems. It's a matter of which are more
important at which time.
Putting raw source code in the documentation is different nightmare,
and I'd rather have the one we have now than the one we'd have if we
did that. With snippets we have the benefit of the compiler and unit
tests and (assuming everything is set up properly, which seems an issue
at the moment) the sample code/etc. will always be correct.
The issue with versioning has been an ongoing issue, since it's not
always just a matter of putting "Since S2.1" after a feature: entire
snippets may only be valid for an S2 revision. In cases where there are
large changes personally I'd set up different snippet prefixes, but
either way, it's a pain.
Also, with snippets, because it's declarative, more can be done to
identify problem code: without snippets (just embedded code) it's more
difficult to track down all the code on the site, make sure it's up to
date, etc.
The theory behind the snippet macro is to implement the ideas for
LiterateProgramming (http://c2.com/cgi/wiki?LiterateProgramming).
Which states: "Note that documentation means a description of the
implementation, /not/ a user manual.". Javadoc already does this!
Javadoc isn't a user manual, it's a reference manual. It can be *used*
as a user manual, but it's not a particularly good environment for
doing so, and lacks most of the features necessary for use as a
general-purpose documentation tool.
(That doesn't necessarily mean that the solution as currently
implemented is optimal, but it beats writing documentation in Javadoc.)
Real single sourcing would be using docbook to generate a website and
a pdf, not what is being done with the snippet macro.
We'd still have some of the same problems. We'd fix some, and add some
different ones.
From the point of view of someone functioning in the role
of a documentation maintainer what would the benefit of
the snippet macro be?
The same benefit it has now: the code and configuration examples work,
because they're functional, tested code. The anti-benefit is that
version-specific documentation is updated as the work is done, not
necessarily as the wiki is exported, so some exported versions won't
match the codebase.
Dave
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
