Better documentation - Githubissues

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/AbstractM
odule.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 reported on code.google.com by ogregoire on 19 May 2009 at 11:10

We're making progress on this. Last week I finally wrote up a proper AOP doc. 
But there's many more features 
that need better tutorial-style documentation:
 - type conversion
 - hierarchical injectors
 - private modules
 - module overrides
 - using the SPI
 - members injectors
 - our exceptions; when to catch what
 - constructing generic types manually; implementing annotation types manually
... and we also need to document best practices.

I'll try to make an effort on this going forward. Documentation is decidedly 
unsexy, especially since a lot of 
folks don't read it anyway! (We get a lot of "Read The Fancy Manual" questions 
on our users' list)

Original comment by limpbizkit on 22 Jun 2009 at 2:20

Changed title: Better documentation
Added labels: Priority-High, Type-Task, Component-Docs

google-code-export / google-guice

Better documentation #374