Hi,
note, I'm not complaining about bad JBoss docs, I find them brief
and enhancable but covering most important things yet, but
Scott M Stark said:
> 3. Read the ultimate docs(the source) ...
I don't agree with this, the ultimate doc is the doc! The
importance of documentation was addressed by SUN with the
JavaDoc tool for low level docs, but the rule applies to high
level docs too.
The 'ultimate docs are the docs' rule especially is true for
Interfaces, which most often is the thing users program
against while getting some or the other implementation at runtime
which might differ greatly while behaving all as specified for
the interface (hopefully). This simply, because for an IF there
is often no or no single impl to look at.
One heavy pitfall of the 'ultimate doc is the source' rule is code
containing a bug. You never should assume that the existing code
is to be interpreted as the doc, which would declare the bug to
be the intended behaviour. But without docs, how could the bug
ever discovered (except for really obvious ones)? By a human,
often the author himself, knowing or guessing the INTENTION of
the code and comparing the intention <=> documentation to the
existing implementation and discovering, that they differ.
Another example: I once had a *.properties file with duplicate
keys (by intention, don't tell you the whole story here) and
wanted to know how java.util.Properties would deal with that.
The docs for Properties.load() are lengthy about the expected
format, but say nothing about dups. So I looked up the impl and
found, that the last duplicate key/value pair in the file was the final
result. Should I now use this knowledge and rely on that behaviour?
Never! Because the impl at any time can change without notice,
the behaviour is undefined, so don't use it. Else you would
introduce very subtle and difficult to find bugs whit the next
JDK or with some subclass of Properties, that does other things
and so on.
Having said that back to work.
And please know, Scott has given sooo much source AND documentation
to JBoss and advice to users on this list that nobody of us avarage
readers here ever can keep up with him.
Very respectful
Georg
___ ___
| + | |__ Georg Rehfeld Woltmanstr. 12 20097 Hamburg
|_|_\ |___ [EMAIL PROTECTED] +49 (40) 23 53 27 10
_______________________________________________
JBoss-user mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-user
