I have found that PropUtils is using a lot of
System.getProperties that somehow influence the
behaviour. Please document all of them with some
stability classification in property sheet arch
Done, not on branch, but will be part of my commit.
I have found nothing in
Updated the arch docs.
BTW, re our discussion about where to document these:
Thinking about it,
I strongly feel the right place for this is in the
docs, not the arch descriptions. The arch descriptions
generally contain a lot of questions that are not
interesting to module authors, or at best are interesting
only once they are building the final application. I
simply don't think people will find them there.
IMO - if the properties are inherently part of the API, or part of an
semi-supported non-normative set of hints to extend the API, then
certainly they belong in the documentation. They could be listed in
the arch desc too, but the docs should be the primary home. If the
props only control the general behavior of the unit of code, of
interest when assembling or running it - logging levels or things like
that - then the arch desc makes more sense.
Maybe all properties should be listed in the arch desc whether or not
they are listed in docs - sounds fine, although I am not sure what the
final purpose of collecting this information is. Maybe useful during
unit testing etc.
I agree that a module author is not likely to look at the arch desc as
the first place to answer a question, nor should we encourage them to
look there first. E.g. when you are looking to see how to subst a new
JNDI impl in Sun's JRE, do you go to the top of the documentation set,
find some link "interesting system properties", click on it, and look
for JNDI? Of course not - you read the JNDI documentation. Part of it,
in the context of explaining how to subst JNDI impls in Sun's JRE,
says to use a certain system property for a certain purpose.
One purpose for collecting property apis in a common format is
described in issue 19781. Another is to be defensive and tell others
that they should not depend on them (making them private, friend, etc.).
I agree that a lot of property descriptions should be visible to the
user. I'd like to point out that arch properties are visible a lot
thru the API page:
If they should be in other documentation as well, then I suggest to
prevent duplication of such information and somehow extract the info
from arch. I can provide an XSL that would do that, if anybody is
While I agree that it may be useful to have a list of all properties
for some purposes, I still think that for *some* properties it is more
sensible to document them inline with the normal documentation, as in
the JNDI example. Extracting them automatically will just produce a
lot of irrelevant information and few people will look at it. However
*most* properties are not part of the API and are not likely to
commonly need customization, so arch seems fine for these.
FWIW, they're now described.
C:\space\nb_all\openide\arch>cvs commit arch-openide-
Checking in arch-openide-propertysheet.xml;
/cvs/openide/arch/arch-openide-propertysheet.xml,v <-- arch-
new revision: 1.11; previous revision: 1.10
Processing log script arguments...
Mailing the commit message to email@example.com (from
I can confirm that the description is there. But if this should have
any additional value, it is necessary to use <api /> tag for that with
stability category. Please look at
to learn how to use the <api /> tag and use it instead of <code />
together with specifying the stability, group, type attributes.
BTW, wouldn't it be more useful to have all of these "no" answers
just be something like <answer boolvalue="false">? Then, for the
yes/no questions, you could simply build a table with check marks,
which would be easier for someone to scan than reading all the
Possible, please give me RFE. Btw. build is broken after your last commit.
Ok. <api> tag is there. But I have thought that you will use it also
for description of properties. Imagine how nice the table at bottom of
the page could look like.
Okay, but how? What API do I call "someRandomJVMFlag"?
BTW, the docs
could be clearer - first, there is a typo ("gropu"); second, an example
would be good.
Couldn't a lot of these questions (like what external APIs someone's
code uses) be automatically answered by source analysis?