[jbossts-issues] [JBoss JIRA] (JBTM-1116) Document configuration

[Tom Jenkinson (JIRA)]

    [ https://issues.jboss.org/browse/JBTM-1116?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12739590#comment-12739590 ] 

Tom Jenkinson commented on JBTM-1116:
-------------------------------------

Hi Gytis,

Initially please can you go through *EnvironmentBean.java and check that the configuration is still in use ("find usages" and if not, mark it as @deprecated. Also make sure that all getters and setters are documented in the javadoc.

Alongside that, although it somewhat contradicts the idea of not documenting the beans in the docs, please can you take an inventory of which configuration items are mentioned in the docs, and where. It may be that these should be removed if they are too low-level and instead to rework the docs to reference the beans at that point.

This will be useful for you to get to know some of the options that are available to JBTM anyway. Also, please can you make sure that each *EnvironmentBean is documented at the class level to describe its purpose. I will give you an example of potentially confusing, ObjectStoreEnvironmentBean. It has configuration for multiple types of object store which only apply to certain object stores, we should somehow ensure it is clear if the bean configuration can be used for multiple purposes, which properties apply to which purpose (at a coarse level, e.g. CacheStore vs ShadowStore).

Please can you ask me to review your pull request (do this via this Jira by linking the pull req) so I can take a look over it.

Also, please don't reformat the code, or move the beans properties around, just add to them or subtract from them. I am sure there will be a temptation to reformat the class to make the related entries closer but this is harder to isolate the changes.

Thanks,
Tom
                
> Document configuration
> ----------------------
>
>                 Key: JBTM-1116
>                 URL: https://issues.jboss.org/browse/JBTM-1116
>             Project: JBoss Transaction Manager
>          Issue Type: Feature Request
>      Security Level: Public(Everyone can see) 
>          Components: Documentation
>            Reporter: Tom Jenkinson
>            Assignee: Gytis Trikleris
>             Fix For: 5.0.0.M3
>
>
> In the pre-Bean days of setting properties, we had all of the TS properties called out in a properties.xml file. In that file there were copious comments to say what the property was for and whether it should be changed. We also documented these properties in the docs. It seems from some investigation that Mike and I have done today that the migration away from the properties file to using MBeans has removed those comments and the docs for the properties. Sometimes the comments do appear in the code.
> If you go back to before everything got turned everything into a Bean (probably 4.6.1 GA) then look in the etc directories.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira