Java API references

The PMDT can include docs create from Java source code comments in regular package docs. When configured as described in this section, the PMDT adds a "Java API" link to the package doc navigation bar at the top of the page. For an example, refer to Java API.

Important
  • A Java API section only appears when you have configured your project to show it.
  • The PMDT does NOT parse JavaDoc comments into doc files. It is a package's responsibility to create DocFX Yaml or markdown files before the package is packed for publishing. Public documentation is generated from the published package, so the required documentation source files must be included.

Adding a Java API section

To add a Java API section to your project:

  1. Create the folder, Documentation~/java_api in the package.
  2. Add "showJavaScriptRef": true, to the projectMetaData.json config file
  3. Add your Yaml or markdown files (or both)
  4. The files must include a DocFX format toc file (typically toc.yml) that contains an entry for each of your Yaml and markdown files, and an index.md file, which serves as the front page of the Java API section of the docs (you are reading an example of such a page right now).

Any approach that translates JavaDoc comments to either DocFX Yaml or Markdown will work.

Java API documentation files

JavaDoc is a longstanding in-source comment format for Java code. Our current doc tools are C# and markdown based and cannot handle JavaDoc directly. To include JavaDoc in your package documentation, you MUST convert your JavaDoc to a format that DocFX understands -- either DocFX Yaml, or markdown. While open source projects exist to perform this conversion, all of the ones we have looked at have issues and drawbacks, so we cannot recommend a specific approach. The possible approaches to achieving the conversion include:

  • Use a JavaDoc doclet to create DocFX Yaml files. Microsoft built an open source doclet, but no longer maintains it. Google forked the doclet and made some modifications, but also doesn't actively maintain it or provide support. Using one of these doclets would require forking the repo, fixing any issues and maintaining it ourselves. The advantage to these doclets is that they provide the required toc file and support cross-package, versioned linking to the Java API docs through standard DocFX uids and xrefs.
  • Use a JavaDoc to markdown convertor. This is a viable approach, though it probably won't have consistent formatting with the C# API docs. And, unless the convertor was specifically written with DocFX in mind, the results might not be complete. For example, you probably won't get a ready-to-use toc file. UIDs won't be assigned in the page Yaml frontmatter, so cross-package, versioned linking won't work. Any particular convertor might have its own idiosyncrasies, too.
  • Use Doxygen and a convertor that either goes directly to DocFX Yaml, or to markdown. Note that Microsoft started with this approach before they wrote their doclet and found that Doxygen lacked support for some JavaDoc elements. (This could have changed since then.)

Required documentation files for the PMDT to publish your Java API docs:

  • Documentation~/java_api/toc.yml: a standard format DocFX table of contents file listing every page in your Java API docs.
  • Documentation~/java_api/index.md: a markdown page that serves as the first page of your Java API docs. Readers land on this page when they click the Java API link on the doc site nav bar.
  • Documentation~/java_api/*.yml: DocFX intermediate Yaml metadata files containing the converted JavaDoc content. You can use Yaml files, markdown files, or both.
  • Documentation~/java_api/*.md: standard markdown files containing the converted JavaDoc content or additional content. You can use Yaml files, markdown files, or both. Markdown files should be assigned a UID in the file's Yaml header to support cross package links. (These also make it easier to link to a Java page from other areas of your own package docs.)
  • Documentation~/projectMetadata.json: The package docs json config file. Add "showJavaScriptRef": true in this file or the Java API link won't be displayed. You must create this file if it doesn't exist.