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
_______________________________________________
Registry-dev mailing list
[email protected]
http://wso2.org/cgi-bin/mailman/listinfo/registry-dev
