commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dave Abelgo (JIRA)" <j...@apache.org>
Subject [jira] [Comment Edited] (CONFIGURATION-610) Improve Configuration Variable Documentation
Date Sun, 01 Nov 2015 01:48:27 GMT

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

Dave Abelgo edited comment on CONFIGURATION-610 at 11/1/15 1:47 AM:
--------------------------------------------------------------------

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.  
   




was (Author: dave abelgo):
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)

Mime
View raw message