Copy ome.api.* documentation to omero.api.* (1)

[sbesson]

See https://trello.com/c/KLCaZX4X/19-copy-ome-api-documentation-to-omero-api

This PR initializes the copy of the Javadoc documentation from the first set of classes of ome.api.* classes into the slice classes.

To review this PR, either build the slice documentation via slice2html or use the published CI documentation. Check the links are all working and there is no obvious error.

[ximenesuk]

@sbesson sorry, I meant to look at this last week but failed to find the published CI docs and then forgot about it. Where are the published docs for the latest merge build?

[sbesson]

@ximenesuk: see https://ci.openmicroscopy.org/view/DEV/job/OMERO-DEV-merge-build/ICE=3.5,jdk=8_LATEST,label=octopus/javadoc/slice2html/ or alternatively download the OMERO.docs artifacts which contains the API documentation.

[ximenesuk]

@sbesson thanks, I was looking in all the wrong places - so long since I have had to look on Jenkins. I'll review tomorrow.

[ximenesuk]

I know this is a copy across from ome but do you want to pick up minor fixes here? If so then there is a stray double quote:

ticket:1434" -> ticket:1434

[ximenesuk]

More generally, none of the trac links resolve to anything. Is that expected in this build as they are external links? The source looks like the periods in the url are represented as double colons. Is that some intermediate representation or is it broken?

[ximenesuk]

The copying on the whole looks fine. Some of my comments relate to minor errors that were in the original ome source. Other comments may well be because this isn't a fully rendered doc with css etc?

[sbesson]

@ximenesuk: commits pushed to address your comments. A couple of comments:

• it looks like @see does not cope well with external hyperlinks so I moved the Trac ticket references to the method descriptions instead
• the @param leakage into the short description seemed to be fixed by adding final dots to the method description consistently with your observation in Copy ome.api.* documentation to omero.api.* (1) #4547 (comment).

[ximenesuk]

This ticket reference needs to be a trac url

[ximenesuk]

The four examples above are more of a question. The documentation doesn't match the code, should this be fixed as the move is made from ome -> omero or left for a later sweep?

[sbesson]

@ximenesuk: I would be in favor or addressing only the mismatching @param PARAMETER here and leave the content/description in sync as we should review it together with ome.api.*. I can push a commit to fix the mismatching property names and the Trac ticket in this PR.

[ximenesuk]

Looks good to merge.