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.
|Summary:||Missing description of JVM properties|
|Product:||platform||Reporter:||Jaroslav Tulach <jtulach>|
|Component:||Explorer||Assignee:||_ tboudreau <tboudreau>|
|Issue Type:||DEFECT||Exception Reporter:|
|Bug Depends on:|
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 firstname.lastname@example.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?