This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 34951 - Missing description of JVM properties
Summary: Missing description of JVM properties
Status: VERIFIED FIXED
Alias: None
Product: platform
Classification: Unclassified
Component: Explorer (show other bugs)
Version: 3.x
Hardware: All All
: P3 blocker (vote)
Assignee: _ tboudreau
URL:
Keywords: ARCH
Depends on:
Blocks: 29447
  Show dependency tree
 
Reported: 2003-07-16 08:51 UTC by Jaroslav Tulach
Modified: 2008-12-22 23:38 UTC (History)
1 user (show)

See Also:
Issue Type: DEFECT
Exception Reporter:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Jaroslav Tulach 2003-07-16 08:51:53 UTC
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
document.
Comment 1 _ tboudreau 2003-07-16 17:29:14 UTC
Done, not on branch, but will be part of my commit.
Comment 2 Jaroslav Tulach 2003-07-17 08:19:56 UTC
I have found nothing in 
openide/arch/arch-openide-propertysheet.xml

Comment 3 _ tboudreau 2003-07-18 18:48:09 UTC
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.
Comment 4 Jesse Glick 2003-07-21 14:51:59 UTC
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.
Comment 5 Jaroslav Tulach 2003-07-23 16:02:09 UTC
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:
http://www.netbeans.org/download/dev/javadoc/#def-api-Lookup

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
interested.
 
Comment 6 Jesse Glick 2003-07-23 18:15:39 UTC
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.
Comment 7 _ tboudreau 2003-09-13 18:25:46 UTC
FWIW, they're now described.

C:\space\nb_all\openide\arch>cvs commit arch-openide-
propertysheet.xml
Checking in arch-openide-propertysheet.xml;
/cvs/openide/arch/arch-openide-propertysheet.xml,v  <--  arch-
openide-propertysh
eet.xml
new revision: 1.11; previous revision: 1.10
done
Processing log script arguments...
Mailing the commit message to cvs@openide.netbeans.org (from 
tboudreau@netbeans.
org)
Comment 8 Jaroslav Tulach 2003-09-15 14:42:47 UTC
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 
http://openide.netbeans.org/tutorial/api.html
to learn how to use the <api /> tag and use it instead of <code />
together with specifying the stability, group, type attributes.
Comment 9 _ tboudreau 2003-09-15 23:24:43 UTC
Done.

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
generated text.
Comment 10 Jaroslav Tulach 2003-09-15 23:42:00 UTC
Possible, please give me RFE. Btw. build is broken after your last commit.
Comment 11 Jaroslav Tulach 2003-09-15 23:43:58 UTC
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.
Comment 12 _ tboudreau 2003-09-16 16:22:42 UTC
Okay, but how?  What API do I call "someRandomJVMFlag"?  

BTW, the docs
http://openide.netbeans.org/tutorial/api.html
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?