Breathe/Sphinx support for Java (origin: Java abstract class methods not supported)

[Caelin]

When generating documentation for a class with abstract method Breathe generates an error for each abstract method in the class. However this is a minor issue as the documentation is still generated properly on the Sphinx page based on the Javadocs comment. The error that is displayed is as follows:

/Users/dkasten/Documents/git/jcmp-team/junos-converter-docs/docs/source/java/jcmptools/configuration/ConfigurationWriter.rst:4: WARNING: Error when parsing function declaration.
If the function has no return type:
  Error in declarator or parameters-and-qualifiers
  Invalid C++ declaration: Expecting "(" in parameters-and-qualifiers. [error at 9]
    abstract StringBuilder writeCommand (ConfigurationValue commandValue, Integer level)
    ---------^
If the function has a return type:
  Error in declarator or parameters-and-qualifiers
  If pointer to member declarator:
    Invalid C++ declaration: Expected '::' in pointer to member (function). [error at 23]
      abstract StringBuilder writeCommand (ConfigurationValue commandValue, Integer level)
      -----------------------^
  If declarator-id:
    Invalid C++ declaration: Expecting "(" in parameters-and-qualifiers. [error at 23]
      abstract StringBuilder writeCommand (ConfigurationValue commandValue, Integer level)
      -----------------------^

And the method declaration that is causing this error is the following:

  /**
   * Write a command to the configuration within the current section.  Must be overridden by the specific implementation subclass of the ConfigurationWriter.
   * 
   * @param commandValue Command string value to write.
   * @param level Indent level for the command.  May not be used by some configuration writers.
   * @return StringBuilder - Generated configuration for the specified command strings.
   * @since 1.0R1.1
   * @see net::juniper::jcmp::tools::configuration::ConfigurationComponent#writeCommand(ConfigurationValue, Integer)
   */
  abstract public StringBuilder writeCommand(ConfigurationValue commandValue, Integer level);

This is for Java code and I know that Java abstract methods don't have the = 0 at the end of the declaration like C++ does so I am not sure if this is a Java specific issue as I have no C++ code to test this issue against.

[jakobandersen]

Thanks for the report. As you indicate, the problem is that Breathe does not know about Java, so the declarations are passed to Sphinx as C++, which Sphinx rightfully complains about.
Two things are needed to resolve this:

1. A Java domain for Sphinx. A quick search resulted in https://bronto-javasphinx.readthedocs.io/en/latest/, but I don't know the state of it.
2. Explicit support for that Java domain in Breathe. An example of what that entails can be found in the relatively recent PR that added C# support: C# Support #550

PRs are very welcome.

[Caelin]

I had looked at Javasphinx before using Breathe and it is no longer maintained and the readme for it says it should only be used for historical use now. So looks like this might not be an easily fixed issue since someone would need to program a new Java domain for Sphinx and also add support for Java in Breathe. However I would like to add it is handling everything even with the error messages it seems as the documentation it is generating is still correct. So for now at least for me I won't plan on coding anything for a Java domain as the C++ one seems to be working. Just with some incorrect warnings/errors that don't seem to be affecting anything though.