Request: (Semi-)permanent HTML ids for sections of the main Mockito.html doc

[GoogleCodeExporter]

I would like to be able to reference document sections (mostly in Mockito.html) 
in a way that won't change as the document is re-organized.  I understand that 
sections may move to other documents, or be deleted.  The request is for while 
the item stays on the page.

For example, I can currently reference the discussion on spy via:
http://docs.mockito.googlecode.com/hg/latest/org/mockito/Mockito.html#16

What happens if it ceases to be item #16?  What about adding an invisible id
http://docs.mockito.googlecode.com/hg/latest/org/mockito/Mockito.html#spies

Original issue reported on code.google.com by lo...@google.com on 8 Mar 2012 at 11:48

[GoogleCodeExporter]

Actually these ids probably won't change as you have noticed they are the base 
of the changelog.

Though it couldn't be bad to have meaningful URLs.

Do you want to contribute ? ;)

Original comment by brice.du...@gmail.com on 9 Mar 2012 at 11:30

• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

I'm contributing in a very different manner.  I'm coordinating Mockito
becoming THE mocking framework for Java at Google.  We are moving from
EasyMock.  We believe Mockito is enough better to justify the transition
(congrats).

For some reason this is keeping me fairly busy.

Original comment by lo...@google.com on 10 Mar 2012 at 1:26

[GoogleCodeExporter]

Hey Lopez. We are very happy you are championing Mockito at G. Let us know if 
you need any help :)

I think the meaningful ids is a very good idea, sad thing we havent thought 
about it earlier. Now it is a bit too late as people might have linked some 
sections already. Rest assured: We will not change the ids, more over we 
probably should add a test that will remind us about this rule in case someone 
changes the ids accidentally.

Cheers!

Original comment by szcze...@gmail.com on 10 Mar 2012 at 1:28

[GoogleCodeExporter]

Btw. What was the driver for Mockito? Was it recent semi-cooperation with 
android guys wrt. mockito for dalvik?

Original comment by szcze...@gmail.com on 10 Mar 2012 at 1:30

[GoogleCodeExporter]

Hi Lopez, your contribution is even more meaningful.
I'm also very to hear your reasons to swith to Mockito.

Original comment by brice.du...@gmail.com on 10 Mar 2012 at 2:13

[GoogleCodeExporter]

Old ids and new (meaningful) ids could coexist couldn't they?

Original comment by dgag...@gmail.com on 10 Mar 2012 at 4:37

[GoogleCodeExporter]

Co-existing id's would be great.

If there are specific docs that you think could use cleaning, we can donate
a bit of time from a tech-writer -- one already volunteered.

I wrote a bunch of stuff for internal consumption about why we should
switch. I'll try to clean it up for public consumption at some point.  The
key points were (from memory):

* Mockito stubs by default, EasyMock verifies by default, which led to
brittle, over-specified tests.

* Mockito is explicit. E.g. InOrder vs createStrictMock()
This is an even bigger issue when the construction is outside of the test
method.

* EasyMock mixes concerns (e.g. strickMock both verifies and require
inOrder)

* EasyMock replay/verify forces the interleaving of "setup" and "testing"
in some cases.  This makes it hard to see what was done "to make it pass",
and what was the actual test. In Mockito these can always be separate.

You can write good tests using EasyMock most of the time.  We failed in ~6
years of attempts to train engineers to do so.  Our experience thus far is
that Engineers write better tests using Mockito.

Original comment by lo...@google.com on 10 Mar 2012 at 10:05

[GoogleCodeExporter]

I think don't want to commit ourselves to not changing the ids.  It's 
conceivable that at some point, we'll add a feature that logically belongs 
somewhere in the middle of the existing features, rather than at the end.  I 
don't think we want to have a section 8.5 (for example) in the javadoc.  I 
fully support adding meaningful anchors to the javadoc, wherever it makes sense 
to do so.

I'm happy to put my hand up to do this, since I'll be touching the javadocs 
anyway before the next release.

Original comment by dmwallace.nz on 11 Mar 2012 at 1:56

[GoogleCodeExporter]

I'm not sure... I kind of like the new features landing at the end of the list. 
This makes it a bit like release notes for noteworthy items.

Original comment by szcze...@gmail.com on 11 Mar 2012 at 5:37

[GoogleCodeExporter]

Yeah same here that's how I though about the main Mockito javadoc.
I though meaningful urls would be interesting, maybe we should thing of id's in 
features. In my opinion we should have coexisting anchors.

Original comment by brice.du...@gmail.com on 11 Mar 2012 at 7:01

[GoogleCodeExporter]

I've added meaningful anchor names to the main paragraph of the Mockito 
javadoc; and checked this in.  Hopefully this is in time to get this change 
into 1.9.1.  Was there any other place where meaningful anchor names should be 
added?

Original comment by dmwallace.nz on 25 Mar 2012 at 6:10

[GoogleCodeExporter]

>Was there any other place where meaningful anchor names should be added?

Don't know. So far we only used anchors in the main document.

Original comment by szcze...@gmail.com on 25 Mar 2012 at 5:25