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

[Chathura Ekanayake (JIRA)]

     [ http://wso2.org/jira/browse/REGISTRY-187?page=all ]

Chathura Ekanayake resolved REGISTRY-187.
-----------------------------------------

    Resolution: Fixed

Added javadocs to all classes and interfaces exposed to Registry users.

> 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