In the Compiler module, operation parameters, operation return fields, and variant enum fields are all represented as Field, which holds an EntityInfo, which in turn holds a comment: DocComment? field.
In Slice, doc comments cannot be written on these fields directly — they are written as @param/@returns tags on the enclosing operation or variant. slice_file_converter.rs bridges this for operation parameters: get_doc_comment_for_parameter finds the matching @param tag on the enclosing operation and synthesizes the parameter's entityInfo.comment from the tag's message, so code generators see parameter documentation without dealing with tag mechanics.
The other two Field contexts never get their entityInfo.comment filled:
-
Return fields: convert_operation converts the fields of returnType with the same convert_parameter used for parameters, but get_doc_comment_for_parameter searches only comment.params — comment.returns is never consulted, so the comment stays unset and @returns messages are parsed, validated, and then dropped. Note ReturnsTag.identifier is optional: an unnamed @returns documents the operation's single return field.
-
Variant enum fields: the comment validator accepts @param on enumerators (only_operations_have_parameters allows Entities::Enumerator), but convert_field reads only the field's own comment, which inline variant fields never have — the variant's @param tags are dropped, so the positional record parameters generated for these fields have no documentation.
Both need the same treatment as operation parameters: synthesize the field's entityInfo.comment from the enclosing entity's tags. No change to the Compiler Slice definitions is required.
In the
Compilermodule, operation parameters, operation return fields, and variant enum fields are all represented asField, which holds anEntityInfo, which in turn holds acomment: DocComment?field.In Slice, doc comments cannot be written on these fields directly — they are written as
@param/@returnstags on the enclosing operation or variant.slice_file_converter.rsbridges this for operation parameters:get_doc_comment_for_parameterfinds the matching@paramtag on the enclosing operation and synthesizes the parameter'sentityInfo.commentfrom the tag's message, so code generators see parameter documentation without dealing with tag mechanics.The other two
Fieldcontexts never get theirentityInfo.commentfilled:Return fields:
convert_operationconverts the fields ofreturnTypewith the sameconvert_parameterused for parameters, butget_doc_comment_for_parametersearches onlycomment.params—comment.returnsis never consulted, so the comment stays unset and@returnsmessages are parsed, validated, and then dropped. NoteReturnsTag.identifieris optional: an unnamed@returnsdocuments the operation's single return field.Variant enum fields: the comment validator accepts
@paramon enumerators (only_operations_have_parametersallowsEntities::Enumerator), butconvert_fieldreads only the field's own comment, which inline variant fields never have — the variant's@paramtags are dropped, so the positional record parameters generated for these fields have no documentation.Both need the same treatment as operation parameters: synthesize the field's
entityInfo.commentfrom the enclosing entity's tags. No change to theCompilerSlice definitions is required.