* Ability to specify multiple Documentation attributes on the same field to generate multiple rows.

* Ability to specify multiple strings on a Documentation attribute to generate multiple columns.

Author: Timwi

External/RT.Util

@@ -65,24 +65,25 @@ public CommandGroupAttribute() { }
 }
 
 /// <summary>
-///     Use this attribute to link a command-line option or command with the help text that describes (documents) it. Suitable
-///     for single-language applications only. See Remarks.</summary>
+///     Use this attribute to write the help text that describes (documents) a command-line option or command. Specifying
+///     multiple strings will create multiple columns in the table. See Remarks.</summary>
 /// <remarks>
 ///     This attribute specifies the documentation in plain text. All characters are printed exactly as specified. You may
 ///     wish to use <see cref="DocumentationRhoMLAttribute"/> to specify documentation with special markup for
 ///     command-line-related concepts, as well as <see cref="DocumentationEggsMLAttribute"/> for an alternative markup
 ///     language without command-line specific concepts.</remarks>
-[AttributeUsage(AttributeTargets.Field | AttributeTargets.Class | AttributeTargets.Method, Inherited = false, AllowMultiple = false), RummageKeepUsersReflectionSafe]
-public class DocumentationAttribute(string documentation) : Attribute
+[AttributeUsage(AttributeTargets.Field | AttributeTargets.Class | AttributeTargets.Method, Inherited = false, AllowMultiple = true), RummageKeepUsersReflectionSafe]
+public class DocumentationAttribute(params string[] documentation) : Attribute
 {
     /// <summary>
-    ///     Gets the console-colored documentation string. Note that this property may throw if the text couldn't be parsed
-    ///     where applicable.</summary>
-    public virtual ConsoleColoredString Text => OriginalText;
+    ///     Gets the console-colored documentation string. Multiple strings may be returned to create multiple columns. Note
+    ///     that this property may throw if the text couldn't be parsed where applicable.</summary>
+    public virtual ConsoleColoredString[] Texts => _converted ??= OriginalTexts.Select(s => (ConsoleColoredString) s).ToArray();
+    private ConsoleColoredString[] _converted;
     /// <summary>Gets a string describing the documentation format to the programmer (not seen by the users).</summary>
     public virtual string OriginalFormat => "Plain text";
     /// <summary>Gets the original documentation string exactly as specified in the attribute.</summary>
-    public string OriginalText { get; private set; } = documentation;
+    public string[] OriginalTexts { get; private set; } = documentation;
 }
 
 /// <summary>
@@ -94,27 +95,29 @@ public class DocumentationLiteralAttribute(string documentation) : Documentation
 }
 
 /// <summary>
-///     Use this attribute to link a command-line option or command with the help text that describes (documents) it. Suitable
-///     for single-language applications only. The documentation is to be specified in <see cref="EggsML"/>, which is
-///     interpreted as described in <see cref="CommandLineParser.Colorize(EggsNode)"/>. See also <see
-///     cref="DocumentationRhoMLAttribute"/> and <see cref="DocumentationAttribute"/>.</summary>
-[AttributeUsage(AttributeTargets.Field | AttributeTargets.Class | AttributeTargets.Method, Inherited = false, AllowMultiple = false), RummageKeepUsersReflectionSafe]
-public class DocumentationEggsMLAttribute(string documentation) : DocumentationAttribute(documentation)
+///     Use this attribute to write the help text that describes (documents) a command-line option or command. Specifying
+///     multiple strings will create multiple columns in the table. The documentation is to be specified in <see
+///     cref="EggsML"/>, which is interpreted as described in <see cref="CommandLineParser.Colorize(EggsNode)"/>.</summary>
+/// <seealso cref="DocumentationAttribute"/>
+/// <seealso cref="DocumentationRhoMLAttribute"/>
+[AttributeUsage(AttributeTargets.Field | AttributeTargets.Class | AttributeTargets.Method, Inherited = false, AllowMultiple = true), RummageKeepUsersReflectionSafe]
+public class DocumentationEggsMLAttribute(params string[] documentation) : DocumentationAttribute(documentation)
 {
     /// <summary>Gets a string describing the documentation format to the programmer (not seen by the users).</summary>
     public override string OriginalFormat => "EggsML";
     /// <summary>
     ///     Gets the console-colored documentation string. Note that this property may throw if the text couldn't be parsed
     ///     where applicable.</summary>
-    public override ConsoleColoredString Text => _parsed ??= CommandLineParser.Colorize(EggsML.Parse(OriginalText));
-    private ConsoleColoredString _parsed;
+    public override ConsoleColoredString[] Texts => _parsed ??= OriginalTexts.Select(text => CommandLineParser.Colorize(EggsML.Parse(text))).ToArray();
+    private ConsoleColoredString[] _parsed;
 }
 
 /// <summary>
-///     Use this attribute to link a command-line option or command with the help text that describes (documents) it. Suitable
-///     for single-language applications only. The documentation is to be specified in <see cref="RhoML"/>, which is
-///     interpreted as described in <see cref="CommandLineParser.Colorize(RhoElement)"/>. See also <see
-///     cref="DocumentationAttribute"/>.</summary>
+///     Use this attribute to write the help text that describes (documents) a command-line option or command. Specifying
+///     multiple strings will create multiple columns in the table. The documentation is to be specified in <see
+///     cref="RhoML"/>, which is interpreted as described in <see cref="CommandLineParser.Colorize(RhoElement)"/>.</summary>
+/// <seealso cref="DocumentationAttribute"/>
+/// <seealso cref="DocumentationEggsMLAttribute"/>
 [AttributeUsage(AttributeTargets.Field | AttributeTargets.Class | AttributeTargets.Method, Inherited = false, AllowMultiple = false), RummageKeepUsersReflectionSafe]
 public class DocumentationRhoMLAttribute(string documentation) : DocumentationAttribute(documentation)
 {
@@ -123,8 +126,8 @@ public class DocumentationRhoMLAttribute(string documentation) : DocumentationAt
     /// <summary>
     ///     Gets the console-colored documentation string. Note that this property may throw if the text couldn't be parsed
     ///     where applicable.</summary>
-    public override ConsoleColoredString Text => _parsed ??= CommandLineParser.Colorize(RhoML.Parse(OriginalText));
-    private ConsoleColoredString _parsed;
+    public override ConsoleColoredString[] Texts => _parsed ??= OriginalTexts.Select(text => CommandLineParser.Colorize(RhoML.Parse(text))).ToArray();
+    private ConsoleColoredString[] _parsed;
 }
 
 /// <summary>

Src/Attributes.cs

@@ -624,12 +624,18 @@ private static Func<int, ConsoleColoredString> getHelpGenerator(Type type, Func<
             }
             helpString.Add(ConsoleColoredString.NewLine);
 
-            // Word-wrap the documentation for the command (if any)
+            // Output the documentation for the command (if any)
             var doc = getDocumentation(type, helpProcessor);
-            foreach (var line in doc.WordWrap(wrapWidth))
+            if (doc.Any(d => d.Length > 0))
             {
-                helpString.Add(line);
-                helpString.Add(ConsoleColoredString.NewLine);
+                var docTable = new TextTable { MaxWidth = wrapWidth, ColumnSpacing = fmtOpt.ColumnSpacing, RowSpacing = fmtOpt.RowSpacing, StretchLastCell = true };
+                foreach (var row in doc)
+                {
+                    for (var x = 0; x < row.Length; x++)
+                        docTable.AddCell(row[x]);
+                    docTable.FinishRow();
+                }
+                helpString.Add(docTable.ToColoredString());
             }
 
 
@@ -650,7 +656,7 @@ private static Func<int, ConsoleColoredString> getHelpGenerator(Type type, Func<
                 var section = field.GetCustomAttribute<SectionAttribute>();
                 if (curTable == null || lastMandatory != mandatory || section != null)
                 {
-                    curTable = new TextTable { MaxWidth = wrapWidth - fmtOpt.LeftMargin, ColumnSpacing = fmtOpt.ColumnSpacing, RowSpacing = fmtOpt.RowSpacing, LeftMargin = fmtOpt.LeftMargin };
+                    curTable = new TextTable { MaxWidth = wrapWidth - fmtOpt.LeftMargin, ColumnSpacing = fmtOpt.ColumnSpacing, RowSpacing = fmtOpt.RowSpacing, LeftMargin = fmtOpt.LeftMargin, StretchLastCell = true };
                     paramsTables.Add((section?.Heading ?? $"{(mandatory ? "Required" : "Optional")} parameters:", curTable));
                     curRow = 0;
                 }
@@ -689,18 +695,22 @@ private static bool createParameterHelpRow(ref int row, TextTable table, FieldIn
         var anyCommandsWithSuboptions = false;
         var cmdName = "<".Color(CmdLineColor.FieldBrackets) + field.Name.Color(CmdLineColor.Field) + ">".Color(CmdLineColor.FieldBrackets);
 
+        int plonkDocumentation(int startCol, int startRow, ConsoleColoredString[][] docs, bool min1)
+        {
+            for (var r = 0; r < docs.Length; r++)
+                for (var c = 0; c < docs[r].Length; c++)
+                    table.SetCell(startCol + c, startRow + r, docs[r][c]);
+            return Math.Max(docs.Length, min1 ? 1 : 0);
+        }
+
         if (field.FieldType.IsEnum)
         {
             // ### ENUM fields, positional
             if (positional)
             {
                 var topRow = row;
                 var doc = getDocumentation(field, helpProcessor);
-                if (doc.Length > 0 || field.FieldType.GetFields(BindingFlags.Static | BindingFlags.Public).All(el => el.IsDefined<UndocumentedAttribute>() || !el.GetCustomAttributes<CommandNameAttribute>().Any()))
-                {
-                    table.SetCell(2, row, doc, colSpan: 4);
-                    row++;
-                }
+                row += plonkDocumentation(2, row, doc, min1: false);
                 foreach (var el in field.FieldType.GetFields(BindingFlags.Static | BindingFlags.Public))
                 {
                     if (el.IsDefined<UndocumentedAttribute>())
@@ -710,32 +720,31 @@ private static bool createParameterHelpRow(ref int row, TextTable table, FieldIn
                         continue;
                     table.SetCell(2, row, attr.Names.Where(n => n.Length <= 2).Select(s => s.Color(CmdLineColor.EnumValue)).JoinColoredString(", "), noWrap: true);
                     table.SetCell(3, row, attr.Names.Where(n => n.Length > 2).Select(s => s.Color(CmdLineColor.EnumValue)).JoinColoredString(Environment.NewLine), noWrap: true);
-                    table.SetCell(4, row, getDocumentation(el, helpProcessor), colSpan: 2);
-                    row++;
+                    row += plonkDocumentation(4, row, getDocumentation(el, helpProcessor), min1: true);
                 }
+                if (row == topRow)
+                    row++;
                 table.SetCell(0, topRow, cmdName, noWrap: true, colSpan: 2, rowSpan: row - topRow);
             }
             // ### ENUM fields, “-x foo” scheme
             else if (field.IsDefined<OptionAttribute>())
             {
                 var topRow = row;
-                row++;
+                row += plonkDocumentation(2, row, getDocumentation(field, helpProcessor), min1: false);
                 foreach (var el in field.FieldType.GetFields(BindingFlags.Static | BindingFlags.Public).Where(e => !e.IsDefined<UndocumentedAttribute>()))
                 {
                     var attr = el.GetCustomAttributes<CommandNameAttribute>().FirstOrDefault();
                     if (attr == null)   // skip the default value
                         continue;
                     table.SetCell(3, row, attr.Names.Where(n => n.Length <= 2).Select(s => s.Color(CmdLineColor.EnumValue)).JoinColoredString(", "), noWrap: true);
                     table.SetCell(4, row, attr.Names.Where(n => n.Length > 2).Select(s => s.Color(CmdLineColor.EnumValue)).JoinColoredString(Environment.NewLine), noWrap: true);
-                    table.SetCell(5, row, getDocumentation(el, helpProcessor));
-                    row++;
+                    row += plonkDocumentation(5, row, getDocumentation(el, helpProcessor), min1: true);
                 }
-                if (row == topRow + 1)
-                    throw new InvalidOperationException($"Enum type {field.FieldType.DeclaringType.FullName}.{field.FieldType} has no values (apart from default value for field {field.DeclaringType.FullName}.{field.Name}).");
+                if (row == topRow)
+                    row++;
                 table.SetCell(0, topRow, field.GetOrderedOptionAttributeNames().Where(o => !o.StartsWith("--")).OrderBy(cmd => cmd.Length).Select(cmd => cmd.Color(CmdLineColor.Option)).JoinColoredString(", "), noWrap: true, rowSpan: row - topRow);
                 table.SetCell(1, topRow, field.GetOrderedOptionAttributeNames().Where(o => o.StartsWith("--")).OrderBy(cmd => cmd.Length).Select(cmd => cmd.Color(CmdLineColor.Option)).JoinColoredString(Environment.NewLine), noWrap: true, rowSpan: row - topRow);
-                table.SetCell(2, topRow, getDocumentation(field, helpProcessor), colSpan: 4);
-                table.SetCell(2, topRow + 1, cmdName, noWrap: true, rowSpan: row - topRow - 1);
+                table.SetCell(2, topRow, cmdName, noWrap: true, rowSpan: row - topRow - 1);
             }
             // ### ENUM fields, “-x” scheme
             else
@@ -744,8 +753,7 @@ private static bool createParameterHelpRow(ref int row, TextTable table, FieldIn
                 {
                     table.SetCell(0, row, el.GetOrderedOptionAttributeNames().Where(o => !o.StartsWith("--")).OrderBy(cmd => cmd.Length).Select(cmd => cmd.Color(CmdLineColor.Option)).JoinColoredString(", "), noWrap: true);
                     table.SetCell(1, row, el.GetOrderedOptionAttributeNames().Where(o => o.StartsWith("--")).OrderBy(cmd => cmd.Length).Select(cmd => cmd.Color(CmdLineColor.Option)).JoinColoredString(Environment.NewLine), noWrap: true);
-                    table.SetCell(2, row, getDocumentation(el, helpProcessor), colSpan: 4);
-                    row++;
+                    row += plonkDocumentation(2, row, getDocumentation(el, helpProcessor), min1: true);
                 }
             }
         }
@@ -765,25 +773,22 @@ private static bool createParameterHelpRow(ref int row, TextTable table, FieldIn
                 var names = ty.GetCustomAttributes<CommandNameAttribute>().First().Names;
                 table.SetCell(2, row, names.Where(n => n.Length <= 2).Select(n => n.Color(CmdLineColor.Command) + asterisk).JoinColoredString(", "), noWrap: true);
                 table.SetCell(3, row, names.Where(n => n.Length > 2).Select(n => n.Color(CmdLineColor.Command) + asterisk).JoinColoredString(Environment.NewLine), noWrap: true);
-                table.SetCell(4, row, getDocumentation(ty, helpProcessor), colSpan: 2);
-                row++;
+                row += plonkDocumentation(4, row, getDocumentation(ty, helpProcessor), min1: true);
             }
             table.SetCell(0, origRow, cmdName, colSpan: 2, rowSpan: row - origRow, noWrap: true);
         }
         // ### All other positional parameters
         else if (positional)
         {
             table.SetCell(0, row, cmdName, noWrap: true, colSpan: 2);
-            table.SetCell(2, row, getDocumentation(field, helpProcessor), colSpan: 4);
-            row++;
+            row += plonkDocumentation(2, row, getDocumentation(field, helpProcessor), min1: true);
         }
         // ### All other non-positional parameters
         else
         {
             table.SetCell(0, row, field.GetOrderedOptionAttributeNames().Where(o => !o.StartsWith("--")).OrderBy(cmd => cmd.Length).Select(cmd => cmd.Color(CmdLineColor.Option)).JoinColoredString(", "), noWrap: true);
             table.SetCell(1, row, field.GetOrderedOptionAttributeNames().Where(o => o.StartsWith("--")).OrderBy(cmd => cmd.Length).Select(cmd => cmd.Color(CmdLineColor.Option)).JoinColoredString(Environment.NewLine), noWrap: true);
-            table.SetCell(2, row, getDocumentation(field, helpProcessor), colSpan: 4);
-            row++;
+            row += plonkDocumentation(2, row, getDocumentation(field, helpProcessor), min1: true);
         }
         return anyCommandsWithSuboptions;
     }
@@ -806,8 +811,8 @@ private static void getFieldsForHelp(Type type, out List<FieldInfo> optionalOpti
         }
     }
 
-    private static ConsoleColoredString getDocumentation(MemberInfo member, Func<ConsoleColoredString, ConsoleColoredString> helpProcessor) =>
-        member.IsDefined<DocumentationAttribute>() ? helpProcessor(member.GetCustomAttributes<DocumentationAttribute>().Select(d => d.Text ?? "").First()) : "";
+    private static ConsoleColoredString[][] getDocumentation(MemberInfo member, Func<ConsoleColoredString, ConsoleColoredString> helpProcessor) =>
+        member.GetCustomAttributes<DocumentationAttribute>().Select(doc => doc.Texts.Select(helpProcessor).ToArray() ?? []).ToArray();
 
     #region Post-build step check
 
@@ -1049,12 +1054,12 @@ private static void checkDocumentation(IPostBuildReporter rep, MemberInfo member
             return;
 
         var attr = member.GetCustomAttributes<DocumentationAttribute>().FirstOrDefault();
-        ConsoleColoredString toCheck = null;
+        ConsoleColoredString[] toCheck = null;
         if (attr != null)
         {
             try
             {
-                toCheck = attr.Text; // this property can throw the first time it's accessed
+                toCheck = attr.Texts; // this property can throw the first time it's accessed
             }
             catch (Exception e)
             {

Src/CommandLineParser.cs

@@ -17,12 +17,12 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.CSharp" Version="4.7.0" />
-    <PackageReference Include="RT.PostBuild" Version="2.0.1776" />
+    <PackageReference Include="RT.PostBuild" Version="2.0.1782" />
   </ItemGroup>
   <ItemGroup Condition="'$(Configuration)' == 'Debug-locallibs'">
     <ProjectReference Include="..\..\RT.Util\RT.Util.Core\RT.Util.Core.csproj" />
   </ItemGroup>
   <ItemGroup Condition="'$(Configuration)' != 'Debug-locallibs'">
-    <PackageReference Include="RT.Util.Core" Version="2.0.1777" />
+    <PackageReference Include="RT.Util.Core" Version="2.0.1782" />
   </ItemGroup>
 </Project>