Add documentation for the OME-XML metadata interfaces

[mlinkert]

Adding proper Javadocs may be a bit tricky, since MetadataStore/MetadataRetrieve? are autogenerated. However, lots of people are confused about how to use these interfaces (esp. in the case of Image/Pixels? attributes), so it would be good to have some sort of documentation that at least explains the most useful methods.

[mlinkert]

Referencing ticket #4531 has changed sprint.

[mlinkert]

Referencing ticket #4531 has changed sprint.

[mlinkert]

Would also be nice to have a page that explains all of the different types of XMLAnnotations (OriginalMetadata? and Modulo) and how to get/set the values, as this isn't easily done from MetadataStore/MetadataRetrieve?.

[jamoore]

Raising up a bit, since after working on ​https://github.com/openmicroscopy/bioformats/pull/820 there may well be some API-breaking decisions we need to make there before 5 goes non-beta.

[rleigh]

This has been implemented for the C++ metadata templates on my cpp-metadatastore-docs branch. The logic can be copied quite easily for javadoc comments for the java templates. For example, I've added logic to xsd-fu to allow it to iterate over the arguments in generated getters/setters so you can generate docs for each method parameter. These can be copied directly from the MetadataStore? and MetadataRetrieve? templates.

[hflynn]

Closing all BF docs tickets and moving them to Trello unless an external is cc'd

[rleigh]

I'd rather we didn't close this. It's not related to Sphinx docs, but to the Javadoc markup of the OME-XML source templates for generating the API reference.

In general, I thought the goal of trello was to keep track of *high level* goals, rather than individual items. Using it for individual items is in my opinion an abuse of trello, and has significant disadvantages:

• there's no useful search in trello, so finding it again will be problematic
• the history of the ticket will be lost
• and trello simply does not scale once you have more than a few hundred cards

Trello looks superficially useful, but after a few months of use, it's clear that it's not in any way a substitute for a proper bug tracker.

Thanks,
Roger

[mlinkert]

The rationale behind closing existing Bio-Formats doc tickets was discussed in the regularly scheduled model/formats meeting on 22 October.

The idea is to link the now-closed tickets on a card for developer documentation (yet to be created), along with any other proposed changes. We are not moving bugs to Trello, but using it to organize the high-level task of reworking Bio-Formats' developer documentation. The ticket history would only be somewhat lost if tickets are not linked from the card.

This is really not the place for complaints on Trello's capabilities, so let's please discuss that separately and with the broader consortium if it's truly an issue.

[rleigh]

​https://github.com/openmicroscopy/bioformats/pull/1820 fixes this issue.