Fix bugs in rendering of source code comments

Revised TActiveTextTextRenderer and made more customisable.

Heavily revised code used in TSourceComments to generate source code
comments from snippet description active text. Also increased indent
size.

Update UTextSnippetDoc re change in TActiveTextTextRenderer & increased
indent size.

Author: delphidabbler

Src/ActiveText.UTextRenderer.pas

@@ -21,23 +21,21 @@ interface
 
 type
   TActiveTextTextRenderer = class(TObject)
-  public
+  strict private
     const
       ///  <summary>Special space character used to indicate the start of a list
       ///  item.</summary>
       ///  <remarks>This special character is a necessary kludge because some
-      ///  c odethat renders active text as formatted plain text strips away
+      ///  code that renders active text as formatted plain text strips away
       ///  leading #32 characters as part of the formatting process. Therefore
       ///  indentation in list items is lost if #32 characters are used for it.
-      ///  NBSP was chosen since it should render the same as a space if calling
-      ///  code doesn't convert it.</remarks>
+      ///  NBSP was chosen since it should render the same as a space if not
+      ///  removed.</remarks>
       LISpacer = NBSP;  // Do not localise. Must be <> #32
       ///  <summary>Bullet character used when rendering unordered list items.
       ///  </summary>
       Bullet = '*';     // Do not localise. Must be <> #32 and <> LISpacer
-  strict private
-    const
-      IndentDelta = 2;
+      DefaultIndentDelta = 2;
     type
       TListKind = (lkNumber, lkBullet);
       TListState = record
@@ -60,6 +58,7 @@       TLIState = record
       fIndent: UInt16;
       fInPara: Boolean;
       fInListItem: Boolean;
+      fIndentDelta: UInt8;
     function CanEmitInline: Boolean;
     procedure AppendToPara(const AText: string);
     procedure InitialiseRender;
@@ -75,9 +74,10 @@       TLIState = record
     destructor Destroy; override;
     property DisplayURLs: Boolean read fDisplayURLs write fDisplayURLs
       default False;
-    function RenderWrapped(ActiveText: IActiveText; const PageWidth, LMargin,
-      ParaOffset: Cardinal; const Prefix: string = '';
-      const Suffix: string  = ''): string;
+    property IndentDelta: UInt8 read fIndentDelta write fIndentDelta
+      default DefaultIndentDelta;
+    function RenderWrapped(ActiveText: IActiveText; const PageWidth,
+      LMargin: Cardinal): string;
   end;
 
 
@@ -122,6 +122,7 @@ constructor TActiveTextTextRenderer.Create;
   fIndent := 0;
   fInPara := False;
   fInListItem := False;
+  fIndentDelta := DefaultIndentDelta;
 end;
 
 destructor TActiveTextTextRenderer.Destroy;
@@ -200,6 +201,21 @@ function TActiveTextTextRenderer.Render(ActiveText: IActiveText): string;
 
 procedure TActiveTextTextRenderer.RenderBlockActionElem(
   Elem: IActiveTextActionElem);
+
+  procedure OpenListContainer(const ListKind: TListKind);
+  begin
+    if (fListStack.Count > 0) and (fInPara) then
+      OutputParagraph;
+    fListStack.Push(TListState.Create(ListKind));
+    Inc(fIndent, IndentDelta);
+  end;
+
+  procedure AddListMarker(const Marker: string);
+  begin
+    fParaBuilder.Append(Marker);
+    fParaBuilder.Append(StringOfChar(NBSP, IndentDelta - Length(Marker)));
+  end;
+
 var
   ListState: TListState;
 begin
@@ -208,22 +224,12 @@ procedure TActiveTextTextRenderer.RenderBlockActionElem(
     begin
       fBlocksStack.Push(Elem.Kind);
       case Elem.Kind of
-        ekPara: {Do nothing} ;
-        ekHeading: {Do nothing} ;
+        ekPara, ekHeading, ekBlock:
+          {Do nothing} ;
         ekUnorderedList:
-        begin
-          if (fListStack.Count > 0) and (fInPara) then
-            OutputParagraph;
-          fListStack.Push(TListState.Create(lkBullet));
-          Inc(fIndent, IndentDelta);
-        end;
+          OpenListContainer(lkBullet);
         ekOrderedList:
-        begin
-          if (fListStack.Count > 0) and (fInPara) then
-            OutputParagraph;
-          fListStack.Push(TListState.Create(lkNumber));
-          Inc(fIndent, IndentDelta);
-       end;
+          OpenListContainer(lkNumber);
         ekListItem:
         begin
           // Update list number of current list
@@ -235,34 +241,19 @@ procedure TActiveTextTextRenderer.RenderBlockActionElem(
           // Act depending on current list kind
           case fListStack.Peek.ListKind of
             lkNumber:
-            begin
-              // Number list: start a new numbered item, with current number
-              fParaBuilder.Append(IntToStr(fListStack.Peek.ListNumber));
-              fParaBuilder.Append(NBSP);
-            end;
+              AddListMarker(IntToStr(fListStack.Peek.ListNumber));
             lkBullet:
-            begin
-              // Bullet list: start a new bullet point
-              fParaBuilder.Append(Bullet + NBSP);
-            end;
+              AddListMarker(Bullet);
           end;
         end;
       end;
     end;
     fsClose:
     begin
       case Elem.Kind of
-        ekPara:
+        ekPara, ekHeading, ekBlock:
           OutputParagraph;
-        ekHeading:
-          OutputParagraph;
-        ekUnorderedList:
-        begin
-          OutputParagraph;
-          fListStack.Pop;
-          Dec(fIndent, IndentDelta);
-        end;
-        ekOrderedList:
+        ekUnorderedList, ekOrderedList:
         begin
           OutputParagraph;
           fListStack.Pop;
@@ -315,7 +306,7 @@ procedure TActiveTextTextRenderer.RenderURL(Elem: IActiveTextActionElem);
 end;
 
 function TActiveTextTextRenderer.RenderWrapped(ActiveText: IActiveText;
-  const PageWidth, LMargin, ParaOffset: Cardinal; const Prefix, Suffix: string):
+  const PageWidth, LMargin: Cardinal):
   string;
 var
   Paras: IStringList;
@@ -367,13 +358,13 @@ function TActiveTextTextRenderer.RenderWrapped(ActiveText: IActiveText;
 
 begin
   Result := '';
-  Paras := TIStringList.Create(Prefix + Render(ActiveText) + Suffix, EOL, True);
+  Paras := TIStringList.Create(Render(ActiveText), EOL, True);
   for Para in Paras do
   begin
     if IsListItem then
     begin
-      Offset := -ParaOffset;
-      ParaIndent := CalcParaIndent + LMargin + ParaOffset;
+      Offset := -IndentDelta;
+      ParaIndent := CalcParaIndent + LMargin + IndentDelta;
     end
     else
     begin

Src/USourceGen.pas

@@ -41,7 +41,7 @@   TSourceComments = class(TNoConstructObject)
     ///  maximum width indented by the given number of spaces on the left,
     ///  optionally truncated to the first paragraph.</summary>
     class function FormatActiveTextCommentInner(ActiveText: IActiveText;
-      const Indent: Cardinal; const Truncate: Boolean): string;
+      const LineWidth: Cardinal; const Truncate: Boolean): string;
   public
 
     ///  <summary>Returns a description of the given comment style.</summary>
@@ -60,7 +60,7 @@   TSourceComments = class(TNoConstructObject)
     ///  <returns>string.Formatted comment or empty string if Style = csNone.
     ///  </returns>
     class function FormatSnippetComment(const Style: TCommentStyle;
-      const TruncateComments: Boolean; const Text: IActiveText): string;
+      const TruncateComments: Boolean; Text: IActiveText): string;
 
     ///  <summary>Formats document's header text as a Pascal comment.</summary>
     ///  <param name="Comments">IStringList [in] List of paragraphs of header
@@ -259,9 +259,11 @@ implementation
 const
   ///  <summary>Maximum number of characters on a source code line.</summary>
   cLineWidth = 80;
-const
   ///  <summary>Size of indenting used for source code, in characters.</summary>
   cIndent = 2;
+  ///  <summary>Size of indenting used for rendering comments from active text.
+  ///  </summary>
+  cCommentIndent = 4;
 
 
 type
@@ -1137,11 +1139,13 @@ class function TSourceComments.CommentStyleDesc(
 end;
 
 class function TSourceComments.FormatActiveTextCommentInner(
-  ActiveText: IActiveText; const Indent: Cardinal; const Truncate: Boolean):
-  string;
+  ActiveText: IActiveText; const LineWidth: Cardinal;
+  const Truncate: Boolean): string;
 var
   Renderer: TActiveTextTextRenderer;
   ProcessedActiveText: IActiveText;
+  Lines: IStringList;
+  Line: string;
 begin
   if Truncate then
     ProcessedActiveText := ActiveText.FirstBlock
@@ -1150,9 +1154,17 @@ class function TSourceComments.FormatActiveTextCommentInner(
   Renderer := TActiveTextTextRenderer.Create;
   try
     Renderer.DisplayURLs := False;
-    Result := Renderer.RenderWrapped(
-      ProcessedActiveText, cLineWidth, Indent, Indent
+    Renderer.IndentDelta := cCommentIndent;
+    Result := '';
+    Lines := TIStringList.Create(
+      Renderer.RenderWrapped(ProcessedActiveText, LineWidth, 0),
+      EOL,
+      True,
+      False
     );
+    for Line in Lines do
+      Result := Result + StringOfChar(' ', cLineWidth - LineWidth) + Line + EOL;
+    Result := StrTrimRight(Result);
   finally
     Renderer.Free;
   end;
@@ -1189,25 +1201,27 @@ class function TSourceComments.FormatHeaderComments(
 end;
 
 class function TSourceComments.FormatSnippetComment(const Style: TCommentStyle;
-  const TruncateComments: Boolean; const Text: IActiveText): string;
+  const TruncateComments: Boolean; Text: IActiveText): string;
 begin
   case Style of
     csNone:
       Result := '';
     csBefore:
-      Result := '{'
-        + EOL
-        + FormatActiveTextCommentInner(Text, cIndent, TruncateComments)
-        + EOL
-        + '}';
+    begin
+      Result := '{' + EOL
+        + FormatActiveTextCommentInner(
+            Text, cLineWidth - cIndent, TruncateComments
+          )
+        + EOL + '}';
+    end;
     csAfter:
-      Result := StrOfChar(TActiveTextTextRenderer.LISpacer, cIndent)
-        + '{'
-        + EOL
-        + FormatActiveTextCommentInner(Text, 2 * cIndent, TruncateComments)
-        + EOL
-        + StrOfChar(TActiveTextTextRenderer.LISpacer, cIndent)
-        + '}';
+    begin
+      Result := StrOfChar(' ', cIndent) + '{' + EOL
+        + FormatActiveTextCommentInner(
+            Text, cLineWidth - 2 * cIndent, TruncateComments
+          )
+        + EOL + StringOfChar(' ', cIndent) + '}';
+    end;
   end;
 end;
 

Src/UTextSnippetDoc.pas

@@ -36,7 +36,7 @@   TTextSnippetDoc = class(TSnippetDoc)
       cPageWidth = 80;
       ///  <summary>Size of a single level of indentation in characters.
       ///  </summary>
-      cIndent = 2;
+      cIndent = 4;
   strict private
     ///  <summary>Renders given active text as word-wrapped paragraphs of width
     ///  cPageWidth.</summary>
@@ -111,8 +111,9 @@ procedure TTextSnippetDoc.RenderActiveText(ActiveText: IActiveText);
   Renderer := TActiveTextTextRenderer.Create;
   try
     Renderer.DisplayURLs := True;
+    Renderer.IndentDelta := cIndent;
     fWriter.WriteLine(
-      Renderer.RenderWrapped(ActiveText, cPageWidth, 0, cIndent)
+      Renderer.RenderWrapped(ActiveText, cPageWidth, 0)
     );
   finally
     Renderer.Free;