Improve documentation

[wernight]

Documentation is missing many important features (or at least should introduce them in the main readme even they are somewhere described if you find):

• Link to the main reference documentation should be first/big:
  -> http://mockito.github.io/mockito/docs/current/org/mockito/Mockito.html
• @Spy: Call the real object but record what has been called
  -> http://mockito.github.io/mockito/docs/current/org/mockito/Mockito.html#spy
• @InjectMocks: Used as a kind of simple dependency injection.
  -> http://mockito.github.io/mockito/docs/current/org/mockito/InjectMocks.html
• @Captor: Used to capture what arguments where called.
  -> http://mockito.github.io/mockito/docs/current/org/mockito/Captor.html
• any() used to verify() something was called with any kind of argument.
  -> http://mockito.github.io/mockito/docs/current/org/mockito/Matchers.html#any()

For most I'd include the relevant import as well. I'd also put an example verify() with any() before even one verifying a specific object was called.

[bric3]

So you'd want this item list in the main README.md ? Or maybe something else in a started guide in the wiki ?

[mockitoguy]

Docs are not great. Do you want to contribute some changes? :)

Down the road, I'd like to have Mockito 'site', static html would be enough.

[wernight]

I'll see to suggest a change to the README.md.

[wernight]

The examples could be rewritten to include some of the main features using the prefered way (e.g., I'd use BDD and annotations).

[wernight]

Another thing that should be done is split http://mockito.github.io/mockito/docs/current/org/mockito/Mockito.html to have the main content there in a new page (ex: http://mockito.github.io/mockito/docs/current/index.html or a completely new page outside) so that Mockito class fields become more readable.

[bric3]

Possible thing to do is to add a maven central badge

[wernight]

@bric3 Yes that could help a bit.

[bric3]

However I kind of like the current Mockito javadoc as is.

[wernight]

@bric3 The issue is that it's the main class with methods etc. and it's mixed with a good document giving the overview of all Mockito features and classes. It's like an index mixed with a class documentation. It may be also part of the reason why going to a field's link doesn't work properly.

[mockitoguy]

Hey Werner. Thanks a lot for looking into improving our documentation. I'm allocating my time other parts of the system (release automation) but documentation will be next :)

[wernight]

I've submitted a pull request for at least the home page.

Still missing:

• Simpler setup, the maven central badge may help (even if it doesn't show the Gradle version of it)
• Moving the documentation index out of Mocking class documentation http://mockito.github.io/mockito/docs/current/org/mockito/Mockito.html
• Writing some better examples, see http://docs.typemock.com/Isolator/##Ref.chm/Documentation/Using.html for how it could be organized (the current kind of "how-to" organization is also good for more in depth).

[bric3]

• Moving the documentation index out of Mocking class documentation http://mockito.github.io/mockito/docs/current/org/mockito/Mockito.html

Not gonna happen. It is our documentation entry point.

• Writing some better examples, see http://docs.typemock.com/Isolator/##Ref.chm/Documentation/Using.html for how it could be organized (the current kind of "how-to" organization is also good for more in depth).

There's always the wiki for that :)

Closing as the PR has been merge, thx again for taking care of the doc.