Status: New
Owner: ----
New issue 374 by [email protected]: Improve wiki and javadoc documentation
http://code.google.com/p/google-guice/issues/detail?id=374
I just had a look at the documentation of classes and I'm a bit skeptical
when I look at it: I expected it to be much more complete.
Guice is a framework that in 95% of the case I don't need the doc, because
it is simple enough or I've seen the doc (usually the wiki) once and the
simpleness of the framework doesn't force me to go look for it once again.
But sometimes, there are great lack of documentation.
For instance, I've watched the video of Bob Lee on Guice home page, and he
mentions the conversion as a good feature of the framework. So I tried to
see what it is and how it looks like. I couldn't find useful information in
the javadoc (except that it throws an exception if needed. But what
exception? Is it at initialization run time, or at instanciation? No clue!)
I've searched the wiki index, no mention of the conversion, then on the FAQ
page of the wiki, still no mention.
Additionaly, when reading the javadoc, I couldn't see at a glance in the
method list of AbstractModule, for instance, what these methods do. I had
to go on the Binder class. Ok, but then why not use the tag {...@inheritdoc} ?
Ok, in this case it's a redirection to another class not the super class,
then why not copy/pasting at least the first line so the method summary
doesn't look undocumented (see
http://google-guice.googlecode.com/svn/trunk/javadoc/com/google/inject/AbstractModule.html#method_summary
). If we use an IDE (like Eclipse in my case), the docs are shown when
hovered. In this case, it is just empty because most of AbstractModule's
method have only a @see tag.
I think that having interesting features is excellent, but not knowing how
to use them is very frustrating. So I'm wondering if it is possible to
invest time on correctly document every feature of Guice and improve the
quality of the javadoc.
Guice is great, really, and if I write this issue, it's not because I'm
blaming it. Not at all! I simply thought that documentation used as much
best practices as Guice recommends to and force people to do ;)
--
You received this message because you are listed in the owner
or CC fields of this issue, or because you starred this issue.
You may adjust your issue notification preferences at:
http://code.google.com/hosting/settings
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"google-guice-dev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/google-guice-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
