Annotation: @Example

[GoogleCodeExporter]

Often, unit tests act as examples of how to use the object under test.  
Unfortunately these handy tidbits tend to be lost under the weight of other 
unit tests and if a developer is not sure where to start it can be perilous to 
even locate the correct set of tests.

Suggestion: introduce an @Example annotation which can be added to methods to 
indicate that the method shows a usage.  This annotation can later be leveraged 
to generate an example book.

One possible element could be "scope" which could be the ClassUnderTest.class, 
or a String with a package name.

 @Example(scope=Frood.class,description="How to apply hoopiness to a frood.")

Original issue reported on code.google.com by jatw...@linuxstuff.org on 9 Mar 2011 at 7:09

[GoogleCodeExporter]

Thanks for the suggestion.  It's not bad, but it feels out of scope for us 
because neither annotations nor testing are primary focuses of ours; we 
basically intend to offer just what we ourselves need in these areas.

I do wish that someone would properly solve the problem of deriving user 
"examples"/"recipe book" documentation by extracting it from unit tests that 
pass, thus solving the staleness problem.  Bob Lee did something very clever 
like this for code samples in his presentations.  Whoever solves that can 
provide whatever annotation or comment convention is required, though.

Original comment by kevinb@google.com on 19 Mar 2011 at 3:31

• Changed state: WontFix
• Added labels: Type-Enhancement

[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:15

• Added labels: MigratedToGitHub

[GoogleCodeExporter]

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

• Added labels: Restrict-AddIssueComment-Commit