[THRIFT-5487] Include @throws in Javadoc when thrown exceptions are documented

• Type: Improvement
• Status: Open
• Priority: Minor
• Resolution: Unresolved
• Affects Version/s: 0.15.0
• Component/s: Java - Compiler
• Assignee: Unassigned
• Reporter: Marcono1234
• Created: 04/Dec/21 16:09
• Updated: 04/Dec/21 16:09

Description

According to the Thrift IDL the declared exceptions of a function are fields and can therefore have a documentation comment. That comment also shows up in the HTML documentation (--gen html). However, in the generated Javadoc the exception documentation is missing. Expected would be that for every declared thrown exception an @throws Javadoc tag is added to the documentation.
Note that Javadoc supports having multiple @throws tags for the same exception type, so no special care has to be taken for that situation.

Example

demo.thrift

namespace java demo

exception SomeException {
}

service Demo {
    /** Demo method */
    void doSomething() throws (
        /** first exception */
        1:SomeException e1,
        /** second exception */
        2:SomeException e2
    ),
}

Expected generated Java code:

Demo.Iface (expected)

public interface Iface {
    /**
      * Demo method
      *
      * @throws SomeException first exception
      * @throws SomeException second exception
      */
     public void doSomething() throws SomeException, SomeException, org.apache.thrift.TException;
}

Actually generated code

Demo.Iface (actual)

public interface Iface {
    /**
      * Demo method
      */
     public void doSomething() throws SomeException, SomeException, org.apache.thrift.TException;
}