[
https://issues.apache.org/jira/browse/THRIFT-6108?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
slavonchick updated THRIFT-6108:
--------------------------------
Description:
As of today, the exceptions thrown in service methods are not included in
generated documentation comments.
I suggest implementing generation of such comments for the exceptions including
both exceptions class reference and the documentation comments.
For example for a method defined as:
{{/**}}
{{* Print 'testMultiException(%s, %s)' with arg0 as '%s' and arg1 as '%s'}}
{{* @param string arg - a string indicating what type of exception to throw}}
{{* if arg0 == "Xception" throw Xception with errorCode = 1001 and message =
"This is an Xception"}}
{{* else if arg0 == "Xception2" throw Xception2 with errorCode = 2002 and
struct_thing.string_thing = "This is an Xception2"}}
{{* else do not throw anything}}
{{* @return Xtruct - an Xtruct with string_thing = arg1}}
{{*/}}
{{Xtruct testMultiException(1: string arg0, 2: string arg1) throws(}}
{{/**}}
{{* Thrown when bad thing happens}}
{{*/}}
{{1: Xception err1,}}
{{/**}}
{{* Thrown when the input is incorrect}}
{{*/}}
{{2: Xception2 err2)}}
The netstd generator would generate:
{{/// <summary>}}
{{/// Print 'testMultiException(%s, %s)' with arg0 as '%s' and arg1 as '%s'}}
{{/// @param string arg - a string indicating what type of exception to throw}}
{{/// if arg0 == "Xception" throw Xception with errorCode = 1001 and message =
"This is an Xception"}}
{{/// else if arg0 == "Xception2" throw Xception2 with errorCode = 2002 and
struct_thing.string_thing = "This is an Xception2"}}
{{/// else do not throw anything}}
{{/// @return Xtruct - an Xtruct with string_thing = arg1}}
{{/// </summary>}}
{{/// <param name="arg0"></param>}}
{{/// <param name="arg1"></param>}}
{{/// <exception cref="global::ThriftTest.Xception">Thrown when bad thing
happens</exception>}}
{{/// <exception cref="global::ThriftTest.Xception2">Thrown when the input is
incorrect</exception>}}
{{[OperationContract]}}
{{[FaultContract(typeof(global::ThriftTest.XceptionFault))]}}
{{[FaultContract(typeof(global::ThriftTest.Xception2Fault))]}}
{{global::System.Threading.Tasks.Task<global::ThriftTest.Xtruct>
testMultiException(string? arg0, string? arg1, CancellationToken
cancellationToken = default);}}
was:
As of today, the exceptions thrown in service methods are not included in
generated documentation comments.
I suggest implementing generation of such comments for the exceptions including
both exceptions class reference and the documentation comments.
For example for a method defined as:
{{/**}}
{{* Print 'testMultiException(%s, %s)' with arg0 as '%s' and arg1 as '%s'}}
{{* @param string arg - a string indicating what type of exception to throw}}
{{* if arg0 == "Xception" throw Xception with errorCode = 1001 and message =
"This is an Xception"}}
{{* else if arg0 == "Xception2" throw Xception2 with errorCode = 2002 and
struct_thing.string_thing = "This is an Xception2"}}
{{* else do not throw anything}}
{{* @return Xtruct - an Xtruct with string_thing = arg1}}
{{*/}}
{{Xtruct testMultiException(1: string arg0, 2: string arg1) throws(}}
{\{ /**}}
{{* Thrown when bad thing happens}}
{{*/}}
{{1: Xception err1,}}
{{/**}}
{{* Thrown when the input is incorrect}}
{{*/}}
{{2: Xception2 err2)}}
The netstd generator would generate:
{{/// <summary>}}
{{/// Print 'testMultiException(%s, %s)' with arg0 as '%s' and arg1 as '%s'}}
{{/// @param string arg - a string indicating what type of exception to throw}}
{{/// if arg0 == "Xception" throw Xception with errorCode = 1001 and message =
"This is an Xception"}}
{{/// else if arg0 == "Xception2" throw Xception2 with errorCode = 2002 and
struct_thing.string_thing = "This is an Xception2"}}
{{/// else do not throw anything}}
{{/// @return Xtruct - an Xtruct with string_thing = arg1}}
{{/// </summary>}}
{{/// <param name="arg0"></param>}}
{{/// <param name="arg1"></param>}}
{{/// <exception cref="global::ThriftTest.Xception">Thrown when bad thing
happens</exception>}}
{{/// <exception cref="global::ThriftTest.Xception2">Thrown when the input is
incorrect</exception>}}
{{[OperationContract]}}
{{[FaultContract(typeof(global::ThriftTest.XceptionFault))]}}
{{[FaultContract(typeof(global::ThriftTest.Xception2Fault))]}}
{{global::System.Threading.Tasks.Task<global::ThriftTest.Xtruct>
testMultiException(string? arg0, string? arg1, CancellationToken
cancellationToken = default);}}
> Generate documentation for exception thrown in service methods
> --------------------------------------------------------------
>
> Key: THRIFT-6108
> URL: https://issues.apache.org/jira/browse/THRIFT-6108
> Project: Thrift
> Issue Type: Improvement
> Components: Documentation
> Reporter: slavonchick
> Priority: Minor
> Labels: features
>
> As of today, the exceptions thrown in service methods are not included in
> generated documentation comments.
>
> I suggest implementing generation of such comments for the exceptions
> including both exceptions class reference and the documentation comments.
>
> For example for a method defined as:
> {{/**}}
> {{* Print 'testMultiException(%s, %s)' with arg0 as '%s' and arg1 as '%s'}}
> {{* @param string arg - a string indicating what type of exception to throw}}
> {{* if arg0 == "Xception" throw Xception with errorCode = 1001 and message =
> "This is an Xception"}}
> {{* else if arg0 == "Xception2" throw Xception2 with errorCode = 2002 and
> struct_thing.string_thing = "This is an Xception2"}}
> {{* else do not throw anything}}
> {{* @return Xtruct - an Xtruct with string_thing = arg1}}
> {{*/}}
> {{Xtruct testMultiException(1: string arg0, 2: string arg1) throws(}}
> {{/**}}
> {{* Thrown when bad thing happens}}
> {{*/}}
> {{1: Xception err1,}}
> {{/**}}
> {{* Thrown when the input is incorrect}}
> {{*/}}
> {{2: Xception2 err2)}}
> The netstd generator would generate:
> {{/// <summary>}}
> {{/// Print 'testMultiException(%s, %s)' with arg0 as '%s' and arg1 as '%s'}}
> {{/// @param string arg - a string indicating what type of exception to
> throw}}
> {{/// if arg0 == "Xception" throw Xception with errorCode = 1001 and message
> = "This is an Xception"}}
> {{/// else if arg0 == "Xception2" throw Xception2 with errorCode = 2002 and
> struct_thing.string_thing = "This is an Xception2"}}
> {{/// else do not throw anything}}
> {{/// @return Xtruct - an Xtruct with string_thing = arg1}}
> {{/// </summary>}}
> {{/// <param name="arg0"></param>}}
> {{/// <param name="arg1"></param>}}
> {{/// <exception cref="global::ThriftTest.Xception">Thrown when bad thing
> happens</exception>}}
> {{/// <exception cref="global::ThriftTest.Xception2">Thrown when the input is
> incorrect</exception>}}
> {{[OperationContract]}}
> {{[FaultContract(typeof(global::ThriftTest.XceptionFault))]}}
> {{[FaultContract(typeof(global::ThriftTest.Xception2Fault))]}}
> {{global::System.Threading.Tasks.Task<global::ThriftTest.Xtruct>
> testMultiException(string? arg0, string? arg1, CancellationToken
> cancellationToken = default);}}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
