Dart: use bullet points to document parameters in comments

CHANGELOG.md

@@ -2,7 +2,9 @@
 
 ## Unreleased
 ### Features:
-  * Dart: added support for type aliases (typedefs).
+ * Dart: added support for type aliases (typedefs).
+### Bug-fixes:
+ * Dart: removed redundant white-spaces from rendered comments for constructors of structures. Adjusted the rendered comments to list parameters using bullet points to improve readability.
 
 ## 13.15.1
 Release date 2025-06-05

gluecodium/src/main/resources/templates/dart/DartFunctionDocs.mustache

@@ -21,7 +21,7 @@
 {{#resolveName comment}}{{#unless this.isEmpty}}{{prefix this "/// "}}
 ///{{/unless}}{{/resolveName}}{{!!
 }}{{#parameters}}{{#set self=this}}{{#resolveName comment}}{{#unless this.isEmpty}}
-/// [{{resolveName self}}] {{prefix this "/// " skipFirstLine=true}}
+/// - [{{resolveName self}}] {{prefix this "/// " skipFirstLine=true}}
 ///{{/unless}}{{/resolveName}}{{/set}}{{/parameters}}{{!!
 }}{{#resolveName returnType.comment}}{{#unless this.isEmpty}}
 /// Returns [{{resolveName returnType.typeRef}}]. {{prefix this "/// " skipFirstLine=true}}

gluecodium/src/main/resources/templates/dart/DartLambdaDocs.mustache

@@ -25,7 +25,7 @@
 {{/ifPredicate}}{{!!
 }}{{#parameters}}{{#set self=this}}{{#resolveName comment}}{{#unless this.isEmpty}}
 ///
-/// [{{self.parameterName}}] {{prefix this "/// " skipFirstLine=true}}
+/// - [{{self.parameterName}}] {{prefix this "/// " skipFirstLine=true}}
 {{/unless}}{{/resolveName}}{{/set}}{{/parameters}}
 {{#if attributes.deprecated}}
 @Deprecated("{{#resolveName attributes.deprecated.message}}{{escape this}}{{/resolveName}}")

gluecodium/src/main/resources/templates/dart/DartStructConstructors.mustache

@@ -78,15 +78,15 @@ Explicit `field constructor` definitions
 }}{{#set struct=this container=this}}{{#fieldConstructors}}
 {{#unless comment.isEmpty}}{{#resolveName comment}}{{#unless this.isEmpty}}{{!!
 }}{{prefix this "  /// "}}
-{{#fields}}
-  /// [{{resolveName}}] {{#resolveName comment}}{{#unless this.isEmpty}}{{!!
-  }}{{prefix this "  /// " skipFirstLine=true}}{{/unless}}{{/resolveName}}
+{{#fields}}{{!!
+}}  /// - [{{resolveName}}] {{#resolveName comment}}{{#unless this.isEmpty}}{{!!
+}}{{prefix this "  /// " skipFirstLine=true}}{{/unless}}{{/resolveName}}
 {{/fields}}{{/unless}}{{/resolveName}}{{/unless}}{{!!
 }}{{#if comment.isEmpty}}{{#resolveName constructorComment}}{{#unless this.isEmpty}}{{!!
 }}{{prefix this "  /// "}}
-{{#fields}}
-  /// [{{resolveName}}] {{#resolveName comment}}{{#unless this.isEmpty}}{{!!
-  }}{{prefix this "  /// " skipFirstLine=true}}{{/unless}}{{/resolveName}}
+{{#fields}}{{!!
+}}  /// - [{{resolveName}}] {{#resolveName comment}}{{#unless this.isEmpty}}{{!!
+}}{{prefix this "  /// " skipFirstLine=true}}{{/unless}}{{/resolveName}}
 {{/fields}}{{/unless}}{{/resolveName}}{{/if}}{{!!
 }}{{#if this.comment.isExcluded}}
   /// @nodoc
@@ -111,10 +111,10 @@ Explicit `field constructor` definitions
 
 }}{{+constructorComment}}{{#resolveName constructorComment}}{{#unless this.isEmpty}}{{!!
 }}{{prefix this "  /// "}}
-{{#fields}}
-  /// [{{resolveName}}] {{#resolveName comment}}{{#unless this.isEmpty}}{{!!
-  }}{{prefix this "  /// " skipFirstLine=true}}{{/unless}}{{/resolveName}}
-{{/fields}}
-{{/unless}}{{/resolveName}}{{/constructorComment}}{{!!
+{{#fields}}{{!!
+}}  /// - [{{resolveName}}] {{#resolveName comment}}{{#unless this.isEmpty}}{{!!
+}}{{prefix this "  /// " skipFirstLine=true}}{{/unless}}{{/resolveName}}
+{{/fields}}{{!!
+}}{{/unless}}{{/resolveName}}{{/constructorComment}}{{!!
 
 }}{{+thisDotFields}}{{#fields}}this.{{resolveName "visibility"}}{{resolveName}}{{#if iter.hasNext}}, {{/if}}{{/fields}}{{/thisDotFields}}

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/comments.dart

@@ -15,7 +15,7 @@ abstract class Comments implements Finalizable {
 
   /// This is some very useful method that measures the usefulness of its input.
   ///
-  /// [inputParameter] Very useful input parameter
+  /// - [inputParameter] Very useful input parameter
   ///
   /// Returns [Comments_Usefulness]. Usefulness of the input
   ///
@@ -24,7 +24,7 @@ abstract class Comments implements Finalizable {
   Comments_Usefulness someMethodWithAllComments(String inputParameter);
   /// This is some very useful method that measures the usefulness of its input.
   ///
-  /// [input] Very useful input parameter
+  /// - [input] Very useful input parameter
   ///
   Comments_Usefulness someMethodWithInputComments(String input);
   /// This is some very useful method that measures the usefulness of its input.
@@ -37,7 +37,7 @@ abstract class Comments implements Finalizable {
   Comments_Usefulness someMethodWithNoComments(String input);
   /// This is some very useful method that does not measure the usefulness of its input.
   ///
-  /// [input] Very useful input parameter
+  /// - [input] Very useful input parameter
   ///
   void someMethodWithoutReturnTypeWithAllComments(String input);
   /// This is some very useful method that does not measure the usefulness of its input.
@@ -57,7 +57,7 @@ abstract class Comments implements Finalizable {
   ///
   void someMethodWithoutReturnTypeOrInputParameters();
 
-  /// [documented] nicely documented
+  /// - [documented] nicely documented
   ///
   String oneParameterCommentOnly(String undocumented, String documented);
 
@@ -191,12 +191,9 @@ class Comments_SomeStruct {
   String? nullableField;
 
   /// This is how easy it is to construct.
-
-  /// [someField] How useful this struct is
+  /// - [someField] How useful this struct is
   /// remains to be seen
-
-  /// [nullableField] Can be `null`
-
+  /// - [nullableField] Can be `null`
   Comments_SomeStruct._(this.someField, this.nullableField);
   Comments_SomeStruct(Comments_Usefulness someField)
     : someField = someField, nullableField = null;
@@ -315,9 +312,9 @@ void smokeCommentsSomestructReleaseFfiHandleNullable(Pointer<Void> handle) =>
 // End of Comments_SomeStruct "private" section.
 /// This is some very useful lambda that does it.
 ///
-/// [p0] Very useful input parameter
+/// - [p0] Very useful input parameter
 ///
-/// [p1] Slightly less useful input parameter
+/// - [p1] Slightly less useful input parameter
 ///
 /// Returns Usefulness of the input
 typedef Comments_SomeLambda = double Function(String, int);

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/comments_interface.dart

@@ -44,14 +44,14 @@ abstract class CommentsInterface implements Finalizable {
 
   /// This is some very useful method that measures the usefulness of its input.
   ///
-  /// [input] Very useful input parameter
+  /// - [input] Very useful input parameter
   ///
   /// Returns [CommentsInterface_Usefulness]. Usefulness of the input
   ///
   CommentsInterface_Usefulness someMethodWithAllComments(String input);
   /// This is some very useful method that measures the usefulness of its input.
   ///
-  /// [input] Very useful input parameter
+  /// - [input] Very useful input parameter
   ///
   CommentsInterface_Usefulness someMethodWithInputComments(String input);
   /// This is some very useful method that measures the usefulness of its input.
@@ -64,7 +64,7 @@ abstract class CommentsInterface implements Finalizable {
   CommentsInterface_Usefulness someMethodWithNoComments(String input);
   /// This is some very useful method that does not measure the usefulness of its input.
   ///
-  /// [input] Very useful input parameter
+  /// - [input] Very useful input parameter
   ///
   void someMethodWithoutReturnTypeWithAllComments(String input);
   /// This is some very useful method that does not measure the usefulness of its input.
@@ -488,7 +488,7 @@ class CommentsInterface$Impl extends __lib.NativeBase implements CommentsInterfa
 
   /// Sets some very useful property.
   ///
-  /// [value] Some very useful property.
+  /// - [value] Some very useful property.
   ///
   set isSomeProperty(CommentsInterface_Usefulness value) {
     final _setFfi = __lib.catchArgumentError(() => __lib.nativeLibrary.lookupFunction<Void Function(Pointer<Void>, Int32, Uint8), void Function(Pointer<Void>, int, int)>('library_smoke_CommentsInterface_isSomeProperty_set__Boolean'));

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/comments_links.dart

@@ -48,7 +48,7 @@ abstract class CommentsLinks implements Finalizable {
   /// Not working for Swift:
   /// * named comment: [][Comments.veryUseful]
   ///
-  /// [inputParameter] Sometimes takes [Comments_SomeEnum.useful]
+  /// - [inputParameter] Sometimes takes [Comments_SomeEnum.useful]
   ///
   /// Returns [Comments_SomeEnum]. Sometimes returns [Comments_SomeEnum.useful]
   ///
@@ -70,9 +70,7 @@ class CommentsLinks_RandomStruct {
   Comments_SomeStruct randomField;
 
   /// constructor comments [Comments_SomeStruct]
-
-  /// [randomField] Some random field [Comments_SomeStruct]
-
+  /// - [randomField] Some random field [Comments_SomeStruct]
   CommentsLinks_RandomStruct(this.randomField);
 }
 

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/deprecation_comments.dart

@@ -33,7 +33,7 @@ abstract class DeprecationComments implements Finalizable {
 
   /// This is some very useful method that measures the usefulness of its input.
   ///
-  /// [input] Very useful input parameter
+  /// - [input] Very useful input parameter
   ///
   /// Returns [DeprecationComments_Usefulness]. Usefulness of the input
   ///
@@ -304,7 +304,7 @@ class DeprecationComments$Impl extends __lib.NativeBase implements DeprecationCo
 
   /// Sets some very useful property.
   ///
-  /// [value] Some very useful property.
+  /// - [value] Some very useful property.
   ///
   @Deprecated("Unfortunately, this property's setter is deprecated.\nUse [Comments.isSomeProperty] instead.")
 
@@ -334,7 +334,7 @@ class DeprecationComments$Impl extends __lib.NativeBase implements DeprecationCo
   }
 
 
-  /// [value] Describes the property but not accessors.
+  /// - [value] Describes the property but not accessors.
   ///
   @Deprecated("Will be removed in v3.2.1.")
 

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/deprecation_comments_only.dart

@@ -25,7 +25,7 @@ abstract class DeprecationCommentsOnly implements Finalizable {
   static final DeprecationCommentsOnly_Usefulness veryUseful = true;
 
 
-  /// [input] Very useful input parameter
+  /// - [input] Very useful input parameter
   ///
   /// Returns [DeprecationCommentsOnly_Usefulness]. Usefulness of the input
   ///

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/excluded_comments.dart

@@ -16,7 +16,7 @@ abstract class ExcludedComments implements Finalizable {
 
   /// This is some very useful method that measures the usefulness of its input.
   ///
-  /// [inputParameter] Very useful input parameter
+  /// - [inputParameter] Very useful input parameter
   ///
   /// Returns [ExcludedComments_Usefulness]. Usefulness of the input
   ///
@@ -119,10 +119,8 @@ class ExcludedComments_SomeStruct {
   ExcludedComments_Usefulness someField;
 
   /// This is how easy it is to construct.
-
-  /// [someField] How useful this struct is
+  /// - [someField] How useful this struct is
   /// remains to be seen
-
   ExcludedComments_SomeStruct(this.someField);
 }
 
@@ -202,9 +200,9 @@ void smokeExcludedcommentsSomestructReleaseFfiHandleNullable(Pointer<Void> handl
 /// This is some very useful lambda that does it.
 /// @nodoc
 ///
-/// [p0] Very useful input parameter
+/// - [p0] Very useful input parameter
 ///
-/// [p1] Slightly less useful input parameter
+/// - [p1] Slightly less useful input parameter
 ///
 /// Returns Usefulness of the input
 typedef ExcludedComments_SomeLambda = double Function(String, int);

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/lambda_comments.dart

@@ -12,7 +12,7 @@ abstract class LambdaComments implements Finalizable {
 
 /// The first line of the doc.
 ///
-/// [p0] The first input parameter
+/// - [p0] The first input parameter
 typedef LambdaComments_WithNoNamedParameters = String Function(String);
 
 // LambdaComments_WithNoNamedParameters "private" section, not exported.
@@ -256,7 +256,7 @@ void smokeLambdacommentsWithnodocsforparametersReleaseFfiHandleNullable(Pointer<
 // End of LambdaComments_WithNoDocsForParameters "private" section.
 /// The first line of the doc.
 ///
-/// [inputParameter] The first input parameter. The second sentence of the first input parameter.
+/// - [inputParameter] The first input parameter. The second sentence of the first input parameter.
 ///
 /// Returns The string.
 typedef LambdaComments_WithNamedParameters = String Function(String inputParameter);

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/multi_line_comments.dart

@@ -27,11 +27,11 @@ abstract class MultiLineComments implements Finalizable {
   /// It has very important parameters.
   /// It has side effects.
   ///
-  /// [input] Very useful input parameter.
+  /// - [input] Very useful input parameter.
   /// You must not confuse it with the second parameter.
   /// But they are similar.
   ///
-  /// [ratio] Not as useful as the first parameter.
+  /// - [ratio] Not as useful as the first parameter.
   /// But still useful.
   /// use a positive value for more happiness.
   ///
@@ -61,6 +61,7 @@ final _smokeMultilinecommentsReleaseHandle = __lib.catchArgumentError(() => __li
 
 
 
+
 class MultiLineComments$Impl extends __lib.NativeBase implements MultiLineComments {
 
   MultiLineComments$Impl(Pointer<Void> handle) : super(handle);

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/platform_comments.dart

@@ -16,7 +16,7 @@ abstract class PlatformComments implements Finalizable {
   void doMagic();
   /// This is some very useful method that measures the usefulness of its input or \esc@pe{s}.
   ///
-  /// [input] Very useful parameter that \[\esc@pe{s}\]
+  /// - [input] Very useful parameter that \[\esc@pe{s}\]
   ///
   /// Returns [bool]. Uselessness [PlatformComments_SomeEnum] of the input
   ///
@@ -215,6 +215,7 @@ final _someMethodWithAllCommentssmokePlatformcommentsSomemethodwithallcommentsSt
 
 
 
+
 class PlatformComments$Impl extends __lib.NativeBase implements PlatformComments {
 
   PlatformComments$Impl(Pointer<Void> handle) : super(handle);

gluecodium/src/test/resources/smoke/comments/output/dart/lib/src/smoke/unicode_comments.dart

@@ -11,7 +11,7 @@ abstract class UnicodeComments implements Finalizable {
 
   /// Süßölgefäß
   ///
-  /// [input] שלום
+  /// - [input] שלום
   ///
   /// Returns [Comments_Usefulness]. товарищ
   ///