[jira] [Commented] (CONFIGURATION-610) Improve Configuration Variable Documentation

["Dave Abelgo (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/CONFIGURATION-610?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14983797#comment-14983797 ] 

Dave Abelgo commented on CONFIGURATION-610:
-------------------------------------------

Just a side note on Documentation, as a novice who has never used commons configuration before.  Having a basic this is how to read a properties file with with versions XXX in getting started would be help full.  I got quite confused as v1.1 has no method to build immutable configuration mentioned in the getting started section. 

I found this 
https://commons.apache.org/proper/commons-configuration/userguide/howto_properties.html#Using_PropertiesConfiguration

However it took me a moment to understand the builder and that the code segment given used is using the wrong generic type. 

 To load this file, you'll write something like:

Parameters params = new Parameters();
FileBasedConfigurationBuilder<Configuration> builder =
    new FileBasedConfigurationBuilder<Configuration>(PropertiesConfiguration.class)
    .configure(params.properties()
        .setFileName("usergui.properties"));

 .......  SHOULD BE  something like this if its going to compile. 
>>>>>>>

    
   private final static String PROPERTIES_FILE_NAME = "system.properties";
   public static final Configuration config;

    public static void read_config() throws ConfigurationException{
        
    Parameters params = new Parameters();
    
    FileBasedConfigurationBuilder<FileBasedConfiguration> builder;
    builder  = new FileBasedConfigurationBuilder<FileBasedConfiguration>(PropertiesConfiguration.class)
        .configure(params.properties()
        .setFileName(PROPERTIES_FILE_NAME));
    
     Configuration config = builder.getConfiguration();
    
    }  

   


> Improve Configuration Variable Documentation
> --------------------------------------------
>
>                 Key: CONFIGURATION-610
>                 URL: https://issues.apache.org/jira/browse/CONFIGURATION-610
>             Project: Commons Configuration
>          Issue Type: Bug
>          Components: Documentation
>    Affects Versions: 2.0-alpha1
>            Reporter: Dan Lamet
>
> The JavaDoc for [Class PropertiesConfiguration |http://commons.apache.org/proper/commons-configuration/apidocs/index.html] lists a very handy feature of Configuration, which is variable substitution.  The behavior can be seen in the example file on the JavaDoc (good).
> But it's not in the preceding list of features.  It would be nice to have a little writeup describing the intended behavior:  What is supposed to happen if you have an undefined ref?  What about nested refs?  What about circular refs? 
> And it was interesting to find that the substitution occurred during get time rather than load (unexpected), and that if one calls the wrong get() method then the substitution will not happen.  (Is that intended behavior?)  This should be called out in the description as well as the individual method JavaDocs.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)