[
https://issues.apache.org/jira/browse/CONFIGURATION-610?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14739240#comment-14739240
]
Oliver Heger commented on CONFIGURATION-610:
--------------------------------------------
The documentation can certainly be improved. You already have thought about it,
would you be willing to provide a patch with your proposed changes?
Note that some further documentation about variable substitution is available
in the user's guide at
http://commons.apache.org/proper/commons-configuration/userguide/howto_basicfeatures.html#Variable_Interpolation.
So maybe it makes sense to improve this chapter and just add a link in the
Javadocs? Also, as all these basic features are implemented by the base class
{{AbstractConfiguration}}, maybe it is better to add comprehensive
documentation there and in the derived classes add a statement like "All basic
features as described for AbstractConfiguration are available as well".
WDYT?
> 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)
