More examples

[GoogleCodeExporter]

There are no examples of how to use the library.

Common use of various parts should not be left to the readers deduction
skills (especially when all one has is javadocs).

In reality, this library is unusable for me.

Please add examples!

D

Original issue reported on code.google.com by did...@gmail.com on 18 Mar 2009 at 4:06

[GoogleCodeExporter]

I did a quick scan and found at least 25 examples in the API documentation.  I 
agree
it should be higher.  I don't understand where the declaration that there are 
NONE
comes from.

We've heard several times that our library is useless unless we write 
documentation
that meets some unspecified standard.  It's a total exaggeration, but still, I 
agree
with the basic notion that more and better documentation is a good thing, and 
I'd
like to have time to do it.  Until I do, if fewer people are able to use the 
library
than should be, I have to live with that.

Original comment by kevin...@gmail.com on 18 Mar 2009 at 4:39

• Changed title: More examples

[GoogleCodeExporter]

Perhaps off-topic to "more examples", but I hope to write a group of wiki pages 
that
somewhat mimics this form:

http://java.sun.com/docs/books/tutorial/collections/index.html

and to some extent this:

http://java.sun.com/javase/6/docs/technotes/guides/collections/overview.html

I know this will help a lot of people.

Original comment by kevin...@gmail.com on 18 Mar 2009 at 4:45

[GoogleCodeExporter]

First of all I'd like to apologize for 'none' - it's easy to think when you 
cant find anything (I browsed through 
the testset too, but could not readily connect my problem/solution to it).

Having said that, first I'd like to ask where can I find them? The trouble with 
javadoc is that is hardly 
documents: it mostly repeats the source in another format ... unless the author 
took a lot of trouble to to 
explain (with examples) in the interface - I hardly ever saw that.

About the unspecified standard, that's a valid remark. However, I'd like to 
point out the boost libraries 
(although c++) where the documentation per library allmost always starts with a 
tutorial containing ready to 
use code snippets demonstrating what exactly this ibrary starts to solve.

For example (see www.boost.org for more):
- parsers: 
http://www.boost.org/doc/libs/1_38_0/libs/spirit/classic/doc/quick_start.html
- network: http://www.boost.org/doc/libs/1_38_0/doc/html/boost_asio.html

Would this suit you?

As to the Sun docs you refer too, they look nice but no meat - still, I cannot 
find examples and examples of 
what your library tries to solve are the only thing you can convince me with I 
should use it.

And note, apache commons does have examples ... (a random pick 
http://commons.apache.org/io)

In conlusion, it would be helpfull to have (a lot of) examples of trivial and 
not so trivial - one of spirits 
examples is a parser for the C language - nature in an obvious place: the first 
page you see.

Best, 

Original comment by did...@gmail.com on 19 Mar 2009 at 7:09

[GoogleCodeExporter]

Original comment by kevin...@gmail.com on 17 Sep 2009 at 5:59

• Added labels: Type-Docs

[GoogleCodeExporter]

I fully sympathize with your concern, but I feel that this bug is simply too 
broad to lead to any tangible action on our part.

That said, please feel free to submit patches which you feel would help improve 
this, and we'll definitely seek to work them in!

Original comment by fry@google.com on 26 Jan 2011 at 9:54

• Changed state: WontFix

[GoogleCodeExporter]

Original comment by kevinb@google.com on 11 May 2012 at 8:55

• Added labels: Type-Documentation
• Removed labels: Type-Docs

[GoogleCodeExporter]

This issue has been migrated to GitHub.

It can be found at https://github.com/google/guava/issues/<id>

Original comment by cgdecker@google.com on 1 Nov 2014 at 4:16

• Added labels: MigratedToGitHub

[GoogleCodeExporter]

Original comment by cgdecker@google.com on 3 Nov 2014 at 9:10

• Added labels: Restrict-AddIssueComment-Commit