Better documentation

_From [ogregoire](https://code.google.com/u/ogregoire/) on May 19, 2009 07:10:31_

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 ;)

_Original issue: http://code.google.com/p/google-guice/issues/detail?id=374_