Merge branch 'feature/85-change-comment-generation-in-units' into develop

Fixes #85

Author: delphidabbler

Docs/Design/FileFormats/config.html

@@ -1262,6 +1262,12 @@ <h4>
   <dd>
     Flag indicating whether multi-paragraph snippet descriptions are to be truncated to the first paragraph only in documentation comments. <code class="value">True</code> &rArr; truncate the description; <code class="value">False</code> &rArr; use the full description.
   </dd>
+  <dt>
+    <code class="key">UseCommentsInUnitImpl</code> (Boolean)
+  </dt>
+  <dd>
+    Flag indicating whether source code comments are repeated in a generated unit's implementation section. <code class="value">True</code> &rArr; emit comments in both the interface and implementation sections; <code class="value">False</code> &rArr; emit comments in the interface section only.
+  </dd>
   <dt>
     <code class="key">UseSyntaxHiliting</code> (Boolean)
   </dt>

Src/FmPreferencesDlg.dfm

@@ -10,30 +10,29 @@ inherited PreferencesDlg: TPreferencesDlg
   TextHeight = 13
   inherited pnlBody: TPanel
     Width = 609
-    Height = 329
+    Height = 353
     ExplicitWidth = 609
-    ExplicitHeight = 329
+    ExplicitHeight = 353
     object pcMain: TPageControl
       Left = 163
       Top = 0
       Width = 446
-      Height = 329
+      Height = 353
       Align = alRight
       MultiLine = True
       TabOrder = 1
-      ExplicitLeft = 159
-      ExplicitHeight = 377
+      ExplicitHeight = 329
     end
     object lbPages: TListBox
       Left = 0
       Top = 0
       Width = 153
-      Height = 329
+      Height = 353
       Align = alLeft
       ItemHeight = 13
       TabOrder = 0
       OnClick = lbPagesClick
-      ExplicitHeight = 377
+      ExplicitHeight = 329
     end
   end
   inherited btnOK: TButton

Src/FrSourcePrefs.dfm

@@ -1,16 +1,16 @@
 inherited SourcePrefsFrame: TSourcePrefsFrame
   Width = 393
-  Height = 327
+  Height = 323
   ExplicitWidth = 393
-  ExplicitHeight = 327
+  ExplicitHeight = 323
   DesignSize = (
     393
-    327)
+    323)
   object gbSourceCode: TGroupBox
     Left = 0
     Top = 0
     Width = 393
-    Height = 201
+    Height = 219
     Anchors = [akLeft, akTop, akRight]
     Caption = ' Source code formatting '
     TabOrder = 0
@@ -56,10 +56,18 @@ inherited SourcePrefsFrame: TSourcePrefsFrame
       Caption = '&Truncate comments to one paragraph'
       TabOrder = 2
     end
+    object chkUnitImplComments: TCheckBox
+      Left = 8
+      Top = 195
+      Width = 345
+      Height = 17
+      Caption = 'Repeat comments in &unit implemenation section'
+      TabOrder = 3
+    end
   end
   object gbFileFormat: TGroupBox
     Left = 0
-    Top = 207
+    Top = 229
     Width = 393
     Height = 81
     Anchors = [akLeft, akTop, akRight]

Src/FrSourcePrefs.pas

@@ -43,6 +43,7 @@   TSourcePrefsFrame = class(TPrefsBaseFrame)
     lblCommentStyle: TLabel;
     lblSnippetFileType: TLabel;
     chkTruncateComments: TCheckBox;
+    chkUnitImplComments: TCheckBox;
     procedure cbCommentStyleChange(Sender: TObject);
     procedure cbSnippetFileTypeChange(Sender: TObject);
   strict private
@@ -181,6 +182,7 @@ procedure TSourcePrefsFrame.Activate(const Prefs: IPreferences;
   SelectSourceFileType(Prefs.SourceDefaultFileType);
   SelectCommentStyle(Prefs.SourceCommentStyle);
   chkTruncateComments.Checked := Prefs.TruncateSourceComments;
+  chkUnitImplComments.Checked := Prefs.CommentsInUnitImpl;
   chkSyntaxHighlighting.Checked := Prefs.SourceSyntaxHilited;
   (fHiliteAttrs as IAssignable).Assign(Prefs.HiliteAttrs);
   fHiliteAttrs.ResetDefaultFont;
@@ -198,13 +200,15 @@ procedure TSourcePrefsFrame.ArrangeControls;
   TCtrlArranger.AlignVCentres(20, [lblCommentStyle, cbCommentStyle]);
   TCtrlArranger.MoveBelow([lblCommentStyle, cbCommentStyle], frmPreview, 8);
   TCtrlArranger.MoveBelow(frmPreview, chkTruncateComments, 8);
-  gbSourceCode.ClientHeight := TCtrlArranger.TotalControlHeight(gbSourceCode)
-    + 10;
 
   TCtrlArranger.AlignVCentres(20, [lblSnippetFileType, cbSnippetFileType]);
   TCtrlArranger.MoveBelow(
     [lblSnippetFileType, cbSnippetFileType], chkSyntaxHighlighting, 8
   );
+  TCtrlArranger.MoveBelow(chkTruncateComments, chkUnitImplComments, 8);
+
+  gbSourceCode.ClientHeight := TCtrlArranger.TotalControlHeight(gbSourceCode)
+    + 10;
   gbFileFormat.ClientHeight := TCtrlArranger.TotalControlHeight(gbFileFormat)
     + 10;
 
@@ -218,7 +222,7 @@ procedure TSourcePrefsFrame.ArrangeControls;
   TCtrlArranger.AlignLefts(
     [
       cbCommentStyle, frmPreview, cbSnippetFileType, chkSyntaxHighlighting,
-      chkTruncateComments
+      chkTruncateComments, chkUnitImplComments
     ],
     Col2Left
   );
@@ -271,6 +275,7 @@ procedure TSourcePrefsFrame.Deactivate(const Prefs: IPreferences);
 begin
   Prefs.SourceCommentStyle := GetCommentStyle;
   Prefs.TruncateSourceComments := chkTruncateComments.Checked;
+  Prefs.CommentsInUnitImpl := chkUnitImplComments.Checked;
   Prefs.SourceDefaultFileType := GetSourceFileType;
   Prefs.SourceSyntaxHilited := chkSyntaxHighlighting.Checked;
 end;
@@ -348,6 +353,7 @@ procedure TSourcePrefsFrame.UpdateControlState;
   chkSyntaxHighlighting.Enabled :=
     TFileHiliter.IsHilitingSupported(GetSourceFileType);
   chkTruncateComments.Enabled := GetCommentStyle <> csNone;
+  chkUnitImplComments.Enabled := GetCommentStyle <> csNone;
 end;
 
 procedure TSourcePrefsFrame.UpdatePreview;

Src/Help/HTML/dlg_prefs_sourcecode.htm

@@ -69,6 +69,12 @@ <h2>
       comment to use just the first paragraph of the snippet's description by
       ticking the <em>Truncate comments to one paragraph</em> check box.
     </p>
+    <p>
+      When descriptive comments are enabled, they are included in the interface
+      section of generated units. You can choose whether or not such comments 
+      are repeated in the unit's implementation section using the <em>Repeat
+      comments in unit implementation section</em> check box.
+    </p>
     <p>
       <strong>Note:</strong> Descriptive comments are not applicable to
       <a href="snippet_freeform.htm">freeform</a> or

Src/UPreferences.pas

@@ -76,6 +76,17 @@ interface
     property TruncateSourceComments: Boolean
       read GetTruncateSourceComments write SetTruncateSourceComments;
 
+    ///  <summary>Gets flag that determines whether source code comments are
+    ///  repeated in a generated unit's implementation section.</summary>
+    function GetCommentsInUnitImpl: Boolean;
+    ///  <summary>Sets flag that determines whether source code comments are
+    ///  repeated in a generated unit's implementation section.</summary>
+    procedure SetCommentsInUnitImpl(const Value: Boolean);
+    ///  <summary>Flag deteminining whether source code comments are repeated in
+    ///  a generated unit's implementation section.</summary>
+    property CommentsInUnitImpl: Boolean
+      read GetCommentsInUnitImpl write SetCommentsInUnitImpl;
+
     ///  <summary>Gets current default file extension / type used when writing
     ///  code snippets to file.</summary>
     function GetSourceDefaultFileType: TSourceFileType;
@@ -326,6 +337,9 @@   TPreferences = class(TInterfacedObject,
       ///  <summary>Flag determining whether multi-paragraph source code is
       ///  truncated to first paragraph in source code comments.</summary>
       fTruncateSourceComments: Boolean;
+      ///  <summary>Flag deteminining whether source code comments are repeated
+      ///  in a generated unit's implementation section.</summary>
+      fCommentsInUnitImpl: Boolean;
       ///  <summary>Indicates whether generated source is highlighted by
       ///  default.</summary>
       fSourceSyntaxHilited: Boolean;
@@ -426,6 +440,16 @@   TPreferences = class(TInterfacedObject,
     ///  <remarks>Method of IPreferences.</remarks>
     procedure SetTruncateSourceComments(const Value: Boolean);
 
+    ///  <summary>Gets flag that determines whether source code comments are
+    ///  repeated in a generated unit's implementation section.</summary>
+    ///  <remarks>Method of IPreferences.</remarks>
+    function GetCommentsInUnitImpl: Boolean;
+
+    ///  <summary>Sets flag that determines whether source code comments are
+    ///  repeated in a generated unit's implementation section.</summary>
+    ///  <remarks>Method of IPreferences.</remarks>
+    procedure SetCommentsInUnitImpl(const Value: Boolean);
+
     ///  <summary>Gets current default file extension / type used when writing
     ///  code snippets to file.</summary>
     ///  <remarks>Method of IPreferences.</remarks>
@@ -690,6 +714,7 @@ procedure TPreferences.Assign(const Src: IInterface);
   Self.fSourceDefaultFileType := SrcPref.SourceDefaultFileType;
   Self.fSourceCommentStyle := SrcPref.SourceCommentStyle;
   Self.fTruncateSourceComments := SrcPref.TruncateSourceComments;
+  Self.fCommentsInUnitImpl := SrcPref.CommentsInUnitImpl;
   Self.fSourceSyntaxHilited := SrcPref.SourceSyntaxHilited;
   Self.fMeasurementUnits := SrcPref.MeasurementUnits;
   Self.fOverviewStartState := SrcPref.OverviewStartState;
@@ -741,6 +766,11 @@ destructor TPreferences.Destroy;
   inherited;
 end;
 
+function TPreferences.GetCommentsInUnitImpl: Boolean;
+begin
+  Result := fCommentsInUnitImpl;
+end;
+
 function TPreferences.GetCustomHiliteColours: IStringList;
 begin
   Result := fHiliteCustomColours;
@@ -852,6 +882,11 @@ function TPreferences.GetWarnings: IWarnings;
   Result := fWarnings;
 end;
 
+procedure TPreferences.SetCommentsInUnitImpl(const Value: Boolean);
+begin
+  fCommentsInUnitImpl := Value;
+end;
+
 procedure TPreferences.SetCustomHiliteColours(const Colours: IStringList);
 begin
   fHiliteCustomColours := Colours;
@@ -985,6 +1020,7 @@ function TPreferencesPersist.Clone: IInterface;
   NewPref.SourceDefaultFileType := Self.fSourceDefaultFileType;
   NewPref.SourceCommentStyle := Self.fSourceCommentStyle;
   NewPref.TruncateSourceComments := Self.fTruncateSourceComments;
+  NewPref.CommentsInUnitImpl := Self.fCommentsInUnitImpl;
   NewPref.SourceSyntaxHilited := Self.fSourceSyntaxHilited;
   NewPref.MeasurementUnits := Self.fMeasurementUnits;
   NewPref.OverviewStartState := Self.fOverviewStartState;
@@ -1069,6 +1105,7 @@ constructor TPreferencesPersist.Create;
     Storage.GetInteger('CommentStyle', Ord(csAfter))
   );
   fTruncateSourceComments := Storage.GetBoolean('TruncateComments', False);
+  fCommentsInUnitImpl := Storage.GetBoolean('UseCommentsInUnitImpl', True);
   fSourceSyntaxHilited := Storage.GetBoolean('UseSyntaxHiliting', False);
 
   // Read printing section
@@ -1151,6 +1188,7 @@ destructor TPreferencesPersist.Destroy;
   Storage.SetInteger('FileType', Ord(fSourceDefaultFileType));
   Storage.SetInteger('CommentStyle', Ord(fSourceCommentStyle));
   Storage.SetBoolean('TruncateComments', fTruncateSourceComments);
+  Storage.SetBoolean('UseCommentsInUnitImpl', fCommentsInUnitImpl);
   Storage.SetBoolean('UseSyntaxHiliting', fSourceSyntaxHilited);
   Storage.Save;
 

Src/USaveUnitMgr.pas

@@ -99,6 +99,7 @@ implementation
   DB.UMetaData,
   UAppInfo,
   UConsts,
+  UPreferences,
   UUrl,
   UUtils;
 
@@ -215,7 +216,11 @@ function TSaveUnitMgr.GenerateSource(const CommentStyle: TCommentStyle;
   const TruncateComments: Boolean): string;
 begin
   Result := fSourceGen.UnitAsString(
-    UnitName, CommentStyle, TruncateComments, CreateHeaderComments
+    UnitName,
+    CommentStyle,
+    TruncateComments,
+    Preferences.TruncateSourceComments,
+    CreateHeaderComments
   );
 end;
 

Src/USourceGen.pas

@@ -198,18 +198,23 @@   TSourceGen = class(TObject)
     ///  <summary>Generates source code of a Pascal unit containing all the
     ///  specified snippets along with any other snippets that are required to
     ///  compile the code.</summary>
-    ///  <param name="UnitName">string [in] Name of unit.</param>
-    ///  <param name="CommentStyle">TCommentStyle [in] Style of commenting used
-    ///  in documenting snippets.</param>
-    ///  <param name="TruncateComments">Boolean [in] Flag indicating whether or
-    ///  not documentation comments are to be truncated at the end of the first
-    ///  paragraph of multi-paragraph text.</param>
-    ///  <param name="HeaderComments">IStringList [in] List of comments to be
-    ///  included at top of unit.</param>
-    ///  <returns>string. Unit source code.</returns>
+    ///  <param name="UnitName"><c>string</c> [in] Name of unit.</param>
+    ///  <param name="CommentStyle"><c>TCommentStyle</c> [in] Style of
+    ///  commenting used in documenting snippets.</param>
+    ///  <param name="TruncateComments"><c>Boolean</c> [in] Flag indicating
+    ///  whether or not documentation comments are to be truncated at the end of
+    ///  the first paragraph of multi-paragraph text.</param>
+    ///  <param name="UseCommentsInImplmentation"><c>Boolean</c> [in] Flag
+    ///  indicating whether or not comments are to be included in the
+    ///  implementation section. Has no effect when <c>CommentStyle</c> =
+    ///  <c>csNone</c>.</param>
+    ///  <param name="HeaderComments"><c>IStringList</c> [in] List of comments
+    ///  to be included at top of unit.</param>
+    ///  <returns><c>string</c>. Unit source code.</returns>
     function UnitAsString(const UnitName: string;
       const CommentStyle: TCommentStyle = csNone;
       const TruncateComments: Boolean = False;
+      const UseCommentsInImplementation: Boolean = False;
       const HeaderComments: IStringList = nil): string;
 
     ///  <summary>Generates source code of a Pascal include file containing all
@@ -585,14 +590,23 @@ class function TSourceGen.IsFileNameValidUnitName(const FileName: string):
 function TSourceGen.UnitAsString(const UnitName: string;
   const CommentStyle: TCommentStyle = csNone;
   const TruncateComments: Boolean = False;
+  const UseCommentsInImplementation: Boolean = False;
   const HeaderComments: IStringList = nil): string;
 var
-  Writer: TStringBuilder;   // used to build source code string
-  Snippet: TSnippet;        // reference to a snippet object
-  Warnings: IWarnings;      // object giving info about any inhibited warnings
+  Writer: TStringBuilder;                    // used to build source code string
+  Snippet: TSnippet;                            // reference to a snippet object
+  Warnings: IWarnings;        // object giving info about any inhibited warnings
+  ImplCommentStyle: TCommentStyle;        // style of comments in implementation
 begin
+  // Set comment style for implementation section
+  if UseCommentsInImplementation then
+    ImplCommentStyle := CommentStyle
+  else
+    ImplCommentStyle := csNone;
+
   // Generate the unit data
   fSourceAnalyser.Generate;
+
   // Create writer object onto string stream that receives output
   Writer := TStringBuilder.Create;
   try
@@ -681,11 +695,14 @@ function TSourceGen.UnitAsString(const UnitName: string;
     for Snippet in fSourceAnalyser.AllRoutines do
     begin
       Writer.AppendLine(
-        TRoutineFormatter.FormatRoutine(CommentStyle, TruncateComments, Snippet)
+        TRoutineFormatter.FormatRoutine(
+          ImplCommentStyle, TruncateComments, Snippet
+        )
       );
       Writer.AppendLine;
     end;
 
+    // class & records-with-methods implementation source code
     for Snippet in fSourceAnalyser.TypesAndConsts do
     begin
       if Snippet.Kind = skClass then