Javadoc references to user guide material

[lesserwhirls]

We have quite a few cases of javadocs referencing users guide material. For example:

https://github.com/Unidata/netcdf-java/blob/327f2b4c1e422541d8853fa8c8fc5b39df989af9/cdm/core/src/main/java/ucar/nc2/NetcdfFile.java#L2137-L2138

and

https://github.com/Unidata/netcdf-java/blob/327f2b4c1e422541d8853fa8c8fc5b39df989af9/cdm/core/src/main/java/ucar/nc2/NetcdfFile.java#L2352

There are two things to address with these types of @see references.

1. Update to reference the new users guide material, e.g. https://www.unidata.ucar.edu/software/netcdf-java/formats/FileTypes.html (which currently 404s) → https://docs.unidata.ucar.edu/netcdf-java/5.4/userguide/file_types.html
2. Create a custom javadoc tag to handle the versioning.

I think the second one would involve extending the standard docklet to look for the tag and do some string processing. Perhaps something like

@refUsersGuide file_types.html

which would produce something like

See also: https://docs.unidata.ucar.edu/netcdf-java/5.4/userguide/file_types.html

The job of the docklet extension would be to look for the custom tag, prepend https://docs.unidata.ucar.edu/netcdf-java/${MAJOR.MINOR}/userguide/ to the text following the tag, and use that string to generate a link. The version number used in the URL would be detected at the javadoc build time, so the link would always point to the right place, so to say.

[JohnLCaron]

In Unidata support archives, such as from this page:

https://www.unidata.ucar.edu/support/help/MailArchives/netcdf/msg13662.html

there are links to reference docs with "current" in the URL:

http://www.unidata.ucar.edu/software/thredds/current/netcdf-java/reference/netcdf4Clibrary.html

These no longer work. Im wondering why that went away? Seems useful to have a version-independent URL.

[lesserwhirls]

There are a few things at play here, but basically, starting with 5, the docs moved from unidata.ucar.edu to docs.unidata.ucar.edu and we also started using the Jekyll documentation system. We do have a current on docs.unidata.ucar.edu (e.g. https://docs.unidata.ucar.edu/netcdf-java/current/userguide/) which is updated as part of the release process. Perhaps we could have the javadocs reference those current urls, but it feels like they should reference the versioned URLs if possible.

[JohnLCaron]

I think referencing the specific version is fine, glad there is a current option. The broken links are due to moving to docs.unidata.... rather than current. Would be nice to have a redirect so the links still work.

I notice that google searches hit random versions of the docs. I wonder if we can tell the crawler to only index current?

[lesserwhirls]

Yeah, it's all been a work in progress. Redirects would be nice, for sure. Currently, that would mean we'd need ~200 hand maintained redirects (between netcdf-java and tds), plus making sure we keep them up-to-date going forward. One thought I had was to mine the logs to see if there are a handful of pages that get hit regularly that now 404, and put in redirects specifically for those (assuming the information on the pages still applies to the current codebase).

I've also noticed google latching on to some version specific urls as well, and I'm not sure what's up there. @oxelson - is that something we can tweak in the sitemap to help keep version specific docs (unidata.ucar.edu or docs.unidata.ucar.edu) out of the search results?

[oxelson]

Hi @lesserwhirls, @JohnLCaron. I can certainly mine the logs, adjust robots.txt, or update site maps if needed. Before we do so, I think we need to sit down and have a look at long-term doc goals so we can find the solution(s) that will require the least continual maintenance going forward. :-)

In the meantime, I'll look at the latest log data to looks for TDS doc-related 404s as a start.

[lesserwhirls]

@oxelson - I'd be happy to do that as well (didn't mean throw you a lump of work)