[Registry-dev] [jira] Created: (REGISTRY-187) Shortcomings in API docs

[Afkham Azeez (JIRA)]

Shortcomings in API docs
------------------------

                 Key: REGISTRY-187
                 URL: http://wso2.org/jira/browse/REGISTRY-187
             Project: WSO2 Registry
          Issue Type: Bug
          Components: core
            Reporter: Afkham Azeez
         Assigned To: Chathura Ekanayake
            Priority: Blocker


The following major API level classes/interfaces have problems in javadocs. At least these classes & interfaces have to be heavily documented

1. CoreRegistry
        No class level doc. Please explain in what type of scenarios ppl will use CoreRegistry & in what type of situation they will use Registry
2. Registry
        Need more class level documentation. See 1.
        String importResource - throws exception lacks javadoc
3.  Resource
       No class level javadoc
       Member attributes not documented
4. MediaTypeHandler
     *  From the class level doc "It defines the three basic methods to be implemented by all media type handlers.." => What are these 3 methods? The interface has more than 3 methods.
     *  Most methods have an undocumented @throws RegistryException
5. URLHandler
      * Undocumented member attributes
     * Instead of having empty methods and overriding them, why not have abstract methods

6. QueryProcessor
     * Undocumented member attributes

7. TaggedResourcePath
        Not documented at all

8. Tag
       Not documented at all

9. Comment
       * No class level doc
       * Member attributes not documented

10. Resource
      * No class level doc
       * Member attributes not documented



In several of the above classes, the explanation for throwing RegistryException is "If an error occurs", which is meaningless, since if nothing went wrong, we would not throw an exception. Better to give an idea of what type of error can occur. Better yet, if you could throw specific exceptions (e.g. DataSourceAccessException if an error occurred while trying to access the registry data source) instead of just RegistryException.



-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://wso2.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira