[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=14984233#comment-14984233 ] 

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

Yes sorry for being a bit long winded.  first.  The section in the example did not compile in my editor with java 1.8 as it would not accept <Configuration> as the correct generic type where as <FileBasedConfiguration> did work.   If I was able to I would have changed the documentation my self. 

The first point was more about documentation navigation. I ended up switching back to v1.10 from configurations2 as I found it more "idomatic" or just easier to code.  With all the switching and googling I soon found my self reading documentation that was for the wrong version of the package and getting more confused.   To avoid confusion one project I use a lot that deals very well with documentation between different version,  is  http://laravel.com/docs/5.1,  When you  you google "laravel validations" a page come up you instantly know what version on the package you are looking at. its also in the URL and you can switch back to the documentation for the version you want.
Mysql has a similar setup that helps navigation. 

Any how commons-configurations 1.10 is working great for me so no complaints once I figured out how to find the correct documentation
Thanks for the hard work putting it together.  

 



 I expected that getting started section might tell me how to simply read a properties file.  But      



> 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)