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.
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.
Done, not on branch, but will be part of my commit.
I have found nothing in openide/arch/arch-openide-propertysheet.xml
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: 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.
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- 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)
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.
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.
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 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?