Jens Geyer created THRIFT-6251:
----------------------------------
Summary: Delphi: generate XML documentation for exceptions thrown
in service methods
Key: THRIFT-6251
URL: https://issues.apache.org/jira/browse/THRIFT-6251
Project: Thrift
Issue Type: Improvement
Components: Delphi - Compiler
Reporter: Jens Geyer
Follow-up to THRIFT-6108, which adds documentation for the exceptions a service
method throws to the cpp, haxe, java, javame, kotlin, netstd and py generators
([PR #3666|https://github.com/apache/thrift/pull/3666]). The Delphi generator
was left out, although it writes method documentation too.
With {{--gen delphi:xmldoc}},
{{t_delphi_generator::generate_delphi_doc(ostream&, t_function*)}} emits
{{<summary>}} and {{<param>}} elements but nothing for the {{throws}} clause.
For
{code}
exception InvalidInput { 1: string message }
service Calculator {
/** Divides two numbers. */
double divide(/** the dividend */ 1: double a, /** the divisor */ 2: double b)
throws (/** Thrown when the divisor is zero. */ 1: InvalidInput err),
void reset() throws (/** Thrown when there is nothing to reset. */ 1:
InvalidInput err)
}
{code}
the generated interface is
{noformat}
{$REGION 'XMLDoc'} /// <summary><para>Divides two numbers.</para>
/// <para></para></summary>
/// <param name="a">the dividend</param>
/// <param name="b">the divisor</param>
{$ENDREGION}
function divide(const a: System.Double; const b: System.Double):
System.Double;
procedure reset();
{noformat}
Neither exception doc reaches the interface methods, and {{reset()}}, which
documents only its exception, gets no doc comment at all.
The netstd implementation from THRIFT-6108 is the closest model, since it
writes XML doc comments as well: one {{<exception cref="...">}} element per
declared exception, with the exception's own doc as its text, XML-escaped
through {{xml_encode()}} (which THRIFT-6108 moves into {{t_oop_generator}}),
and written even when the method itself has no doc. For {{divide}} above netstd
generates
{noformat}
/// <exception cref="InvalidInput">Thrown when the divisor is
zero.</exception>
{noformat}
_Drafted with AI assistance (Claude Opus 5)._
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
