commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Oliver Heger (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (CONFIGURATION-610) Improve Configuration Variable Documentation
Date Thu, 10 Sep 2015 18:02:45 GMT

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

Mime
View raw message