[
https://issues.apache.org/jira/browse/THRIFT-6108?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jens Geyer 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:
{code}
/**
* 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)
{code}
The netstd generator would generate:
{code}
/// <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);
{code}
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
> Time Spent: 2h
> Remaining Estimate: 0h
>
> 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:
> {code}
> /**
> * 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)
> {code}
> The netstd generator would generate:
> {code}
> /// <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);
> {code}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
