CodeSnip Old Code (SVN)

--- a/trunk/Src/FrCodeGenPrefs.pas
+++ b/trunk/Src/FrCodeGenPrefs.pas
@@ -78,29 +78,65 @@
     procedure actPreviewUpdate(Sender: TObject);
     procedure btnPredefinedClick(Sender: TObject);
   private
-    fWarnings: IWarnings;
+    fWarnings: IWarnings; // Object that stores details of warnings
     procedure PopulateLV;
+      {Populates list view with details of warnings.
+      }
     procedure AddWarningToLV(const Warning: TWarning);
+      {Adds details of a warning to list view.
+        @param Warning [in] Warning to be added.
+      }
     function FormatCompilerVer(const Ver: Single): string;
+      {Formats compiler version number as a string.
+        @param Ver [in] Version number to be formatted.
+        @return Formatted string.
+      }
     function IndexOfSymbolInLV(const Symbol: string): Integer;
+      {Gets the index of the list item containing a warning symbol in the list
+      view.
+        @param Symbol [in] Symbol to be found.
+        @return Index of required list view item or -1 if not found.
+      }
     function GetSymbol(out Symbol: string): Boolean;
+      {Gets warning symbol from edit control.
+        @param Symbol [out] Required symbol, trimmed of white space. Undefined
+          if not valid.
+        @return True if symbol is non-empty string, False if not.
+      }
     function IsValidSymbol: Boolean;
+      {Checks if symbol entered in edit control is valid.
+        @return True if valid, False if not.
+      }
     function GetCompilerVersion(out Ver: Single): Boolean;
+      {Gets a compiler version number from edit control.
+        @param Ver [out] Required version number. Undefined if not valid.
+        @return True if version number is valid, False if not.
+      }
     function IsValidCompilerVersion: Boolean;
+      {Checks if compiler version entered in edit control is valid.
+        @return True if valid, False if not.
+      }
     procedure PopulatePreDefCompilerMenu;
+      {Populates pre-defined compiler version pop-up menu with menu items.
+      }
     procedure PreDefCompilerMenuClick(Sender: TObject);
+      {Handler for click events on any pre-defined compiler menu item. Stores
+      required compiler version in associated edit control.
+        @param Sender [in] Reference to clicked menu item.
+      }
   public
-    // todo: complete and revise all method comments
     constructor Create(AOwner: TComponent); override;
-      {Class constructor. Sets up frame and populates controls.
+      {Constructor. Sets up frame and populates controls.
         @param AOwner [in] Component that owns frame.
       }
     procedure Activate(const Prefs: IPreferences); override;
-      {Called when page activated. Must update controls from preferences.
+      {Called when page activated. Records details of warnings and updates
+      controls accordingly.
         @param Prefs [in] Object that provides info used to update controls.
       }
     procedure Deactivate(const Prefs: IPreferences); override;
-      {Called when page is deactivated. Must store information entered by user.
+      {Called when page is deactivated. Updates warnings and preferences objects
+      from information entered in tab.
         @param Prefs [in] Object used to store information.
       }
     procedure ArrangeControls; override;
@@ -113,9 +149,7 @@
       }
     class function Index: Byte; override;
       {Provides an index number that determines the order in which the tabs
-      containing frames are displayed in the preferences dialog box. Gaps
-      between indexes should be left where possible to allow for insertion of
-      new entries at a later date.
+      containing frames are displayed in the preferences dialog box.
         @return Required index number.
       }
   end;
@@ -133,24 +167,42 @@
 {$R *.dfm}
 
 type
+  {
+  TPreDefCompilerMenuItem:
+    Custom menu item with additional property to store a compiler version and
+    extended constructor that takes all required properties and event handlers.
+  }
   TPreDefCompilerMenuItem = class(TMenuItem)
   strict private
-    fCompilerVer: Single;
+    fCompilerVer: Single; // Value of CompilerVer property
   public
     constructor Create(AOwner: TComponent; const ACaption: string;
       const ACompilerVer: Single; const AClickHandler: TNotifyEvent);
       reintroduce;
+      {Constructor. Used to fully create a menu item with all required
+      properties and event handlers.
+        @param AOwner [in] Component that owns menu item.
+        @param ACaption [in] Name of compiler displayed in menu item's caption.
+        @param ACompilerVer [in] Version number of compiler named in ACaption.
+        @param AClickHandler [in] Menu item's OnClick event handler.
+      }
     property CompilerVer: Single read fCompilerVer write fCompilerVer;
+      {Version number of compiler whose name is displayed in menu item's
+      Caption}
   end;
 
 
 { TCodeGenPrefsFrame }
 
 procedure TCodeGenPrefsFrame.actAddExecute(Sender: TObject);
-var
-  W: TWarning;
-  Symbol: string;
-  CompilerVer: Single;
+  {Creates a new warning from data entered in edit controls and adds it to the
+  list view and records in warnings list.
+    @param Sender [in] Not used.
+  }
+var
+  W: TWarning;          // new warning
+  Symbol: string;       // name of warning's symbol
+  CompilerVer: Single;  // min compiler version that supports warning
 begin
   // Add new warning from edit controls to fWarnings and list view
   GetSymbol(Symbol);
@@ -158,54 +210,75 @@
   W := TWarning.Create(Symbol, CompilerVer);
   fWarnings.Add(W);
   AddWarningToLV(W);
+  // Select new list item and make it visible
   lvWarnings.Selected := lvWarnings.Items[IndexOfSymbolInLV(Symbol)];
   lvWarnings.Selected.MakeVisible(False);
 end;
 
 procedure TCodeGenPrefsFrame.actAddUpdate(Sender: TObject);
-var
-  CanUpdate: Boolean;
-
+  {Updates state of action that creates and records a warning. Action enabled
+  only if data in edit controls is valid.
+    @param Sender [in] Not used.
+  }
+var
+  CanAdd: Boolean; // flag that records whether a warning can be added to list
+
+  // ---------------------------------------------------------------------------
   function SymbolIsDuplicate: Boolean;
+    {Checks if symbol entered in edit control is a duplicate of an existing
+    symbol in the list view.
+      @return True if duplicate, False if not.
+    }
   var
-    Symbol: string;
+    Symbol: string; // symbol from edit control
   begin
     GetSymbol(Symbol);
     Result := IndexOfSymbolInLV(Symbol) >= 0;
   end;
-
-begin
-  // Can add if (1) Symbol is non-empty and isn't already in list (2) compiler
-  // version is valid
-  CanUpdate := True;
+  // ---------------------------------------------------------------------------
+
+begin
+  CanAdd := True;
   if not IsValidSymbol then
-    CanUpdate := False
+    CanAdd := False
   else if SymbolIsDuplicate then
-    CanUpdate := False
+    CanAdd := False
   else if not IsValidCompilerVersion then
-    CanUpdate := False;
-  actAdd.Enabled := CanUpdate;
+    CanAdd := False;
+  actAdd.Enabled := CanAdd;
 end;
 
 procedure TCodeGenPrefsFrame.actDeleteExecute(Sender: TObject);
-var
-  Symbol: string;
+  {Deletes selected warning from warnings list and list view.
+    @param Sender [in] Not used.
+  }
+var
+  Symbol: string; // symbol of selected warning
 begin
   // Delete selected warning
   Symbol := Trim(lvWarnings.Selected.Caption);
   lvWarnings.Selected.Delete;
   fWarnings.Delete(Symbol);
+  // Ensure nothing selected in list view and clear edit controls
   lvWarnings.Selected := nil;
   edSymbol.Text := '';
   edMinCompiler.Text := '';
 end;
 
 procedure TCodeGenPrefsFrame.actDeleteUpdate(Sender: TObject);
+  {Updates state of action that deletes a warning. Action enabled only if an
+  item is selected in list view.
+    @param Sender [in] Not used.
+  }
 begin
   actDelete.Enabled := Assigned(lvWarnings.Selected);
 end;
 
 procedure TCodeGenPrefsFrame.Activate(const Prefs: IPreferences);
+  {Called when page activated. Records details of warnings and updates controls
+  accordingly.
+    @param Prefs [in] Object that provides info used to update controls.
+  }
 begin
   (fWarnings as IAssignable).Assign(Prefs.Warnings);
   chkSwitchOff.Checked := fWarnings.SwitchOff;
@@ -213,23 +286,36 @@
 end;
 
 procedure TCodeGenPrefsFrame.actPreviewExecute(Sender: TObject);
+  {Displays compiler directives used to switch off listed warnings in a dialog
+  box.
+    @param Sender [in] Not used.
+  }
 resourcestring
+  // TODO: Change this caption to something like "Compiler Directives"
   sCaption = 'Conditional compilation code';
 begin
   TPreviewDlg.Execute(Self.Owner, fWarnings.Render, sCaption);
 end;
 
 procedure TCodeGenPrefsFrame.actPreviewUpdate(Sender: TObject);
+  {Updates state of action that displays preview of compiler directives. Enabled
+  only if switching off of warnings is allowed and there are warnings in list
+  view.
+    @param Sender [in] Not used.
+  }
 begin
   actPreview.Enabled := (lvWarnings.Items.Count > 0) and chkSwitchOff.Checked;
 end;
 
 procedure TCodeGenPrefsFrame.actUpdateExecute(Sender: TObject);
-var
-  OldSymbol: string;
-  NewSymbol: string;
-  NewCompilerVer: Single;
-  SelItem: TListItem;
+  {Updates selected warning from data entered in edit controls.
+    @param Sender [in] Not used.
+  }
+var
+  OldSymbol: string;      // symbol associated with selected warning
+  NewSymbol: string;      // new symbol from edit control
+  NewCompilerVer: Single; // new compiler version from edit control
+  SelItem: TListItem;     // reference to selected item in list view
 begin
   // Update selected warning with new values: update display and warning list
   GetSymbol(NewSymbol);
@@ -238,29 +324,39 @@
   OldSymbol := Trim(SelItem.Caption);
   SelItem.Caption := NewSymbol;
   SelItem.SubItems[0] := FormatCompilerVer(NewCompilerVer);
+  // we update warnings by deleting old one and adding updated version
   fWarnings.Delete(OldSymbol);
   fWarnings.Add(TWarning.Create(NewSymbol, NewCompilerVer));
+  // Ensure updated item is still selected in list view and is visible
   lvWarnings.Selected := SelItem;
   SelItem.MakeVisible(False);
 end;
 
 procedure TCodeGenPrefsFrame.actUpdateUpdate(Sender: TObject);
-var
-  CanUpdate: Boolean;
-
+  {Updates state of action that updates a warning. Action enabled only if data
+  in edit controls is valid.
+    @param Sender [in] Not used.
+  }
+var
+  CanUpdate: Boolean;   // flag that indicates if a warning can be updated
+
+  // ---------------------------------------------------------------------------
   function SymbolIsDuplicate: Boolean;
+    {Checks if symbol entered in edit control is a duplicate of an existing
+    symbol in the list view, other than that of the selected warning.
+      @return True if duplicate, False if not.
+    }
   var
-    LIIdx: Integer;
-    Symbol: string;
+    Symbol: string; // symbol entered in edit control
+    LIIdx: Integer; // index of list item with Symbol as caption
   begin
     GetSymbol(Symbol);
     LIIdx := IndexOfSymbolInLV(Symbol);
     Result := (LIIdx >= 0) and (LIIdx <> lvWarnings.Selected.Index);
   end;
-
-begin
-  // Can edit if (1) Symbol is non-empty (2) Symbol is not already in list,
-  // except for selected entry (3) compiler version is valid
+  // ---------------------------------------------------------------------------
+
+begin
   CanUpdate := True;
   if lvWarnings.Selected = nil then
     CanUpdate := False
@@ -274,8 +370,11 @@
 end;
 
 procedure TCodeGenPrefsFrame.AddWarningToLV(const Warning: TWarning);
-var
-  LI: TListItem;
+  {Adds details of a warning to list view.
+    @param Warning [in] Warning to be added.
+  }
+var
+  LI: TListItem;  // new list item for warning
 begin
   LI := lvWarnings.Items.Add;
   LI.Caption := Warning.Symbol;
@@ -283,6 +382,8 @@
 end;
 
 procedure TCodeGenPrefsFrame.ArrangeControls;
+  {Arranges controls on frame. Called after frame has been sized.
+  }
 begin
   btnPreview.Left := Width - btnPreview.Width;
   lvWarnings.Width := Width;
@@ -303,6 +404,10 @@
 end;
 
 procedure TCodeGenPrefsFrame.btnPredefinedClick(Sender: TObject);
+  {Click event handler for pre-defined compiler versions button. Drops down
+  associated popup menu.
+    @param Sender [in] Not used.
+  }
 var
   PopupPos: TPoint; // place where menu pops up
 begin
@@ -313,11 +418,18 @@
 end;
 
 procedure TCodeGenPrefsFrame.chkSwitchOffClick(Sender: TObject);
+  {Click event handler for "switch off warnings" check box. Updated warnings
+  object per state of check box.
+    @param Sender [in] Not used.
+  }
 begin
   fWarnings.SwitchOff := chkSwitchOff.Checked;
 end;
 
 constructor TCodeGenPrefsFrame.Create(AOwner: TComponent);
+  {Constructor. Sets up frame and populates controls.
+    @param AOwner [in] Component that owns frame.
+  }
 begin
   inherited;
   HelpKeyword := 'CodeGenPrefs';
@@ -326,12 +438,20 @@
 end;
 
 procedure TCodeGenPrefsFrame.Deactivate(const Prefs: IPreferences);
+  {Called when page is deactivated. Updates warnings and preferences objects
+  from information entered in tab.
+    @param Prefs [in] Object used to store information.
+  }
 begin
   fWarnings.SwitchOff := chkSwitchOff.Checked;
   Prefs.Warnings := fWarnings;
 end;
 
 function TCodeGenPrefsFrame.DisplayName: string;
+  {Provides caption that is displayed in the tab sheet that contains this frame
+  when displayed in the preference dialog box.
+    @return Required display name.
+  }
 resourcestring
   sDisplayName = 'Code Generation'; // display name
 begin
@@ -346,7 +466,7 @@
     @param Key [in/out] Key that was pressed. Set to #0 to inhibit if not valid.
   }
 begin
-  { TODO: extract common code from here and FrPrintingPrefs.NumEditKeyPress
+  { TODO: Extract common code from here and FrPrintingPrefs.NumEditKeyPress
           and move into suitable routine in UKeysHelper }
   if Key = DecimalSeparator then
   begin
@@ -362,13 +482,21 @@
 end;
 
 function TCodeGenPrefsFrame.FormatCompilerVer(const Ver: Single): string;
+  {Formats compiler version number as a string.
+    @param Ver [in] Version number to be formatted.
+    @return Formatted string.
+  }
 begin
   Result := Format('%.2f', [Ver]);
 end;
 
 function TCodeGenPrefsFrame.GetCompilerVersion(out Ver: Single): Boolean;
-var
-  ExtVer: Extended;
+  {Gets a compiler version number from edit control.
+    @param Ver [out] Required version number. Undefined if not valid.
+    @return True if version number is valid, False if not.
+  }
+var
+  ExtVer: Extended;   // version number as Extended float
 begin
   Result := TryStrToFloat(Trim(edMinCompiler.Text), ExtVer);
   if Result then
@@ -376,19 +504,32 @@
 end;
 
 function TCodeGenPrefsFrame.GetSymbol(out Symbol: string): Boolean;
+  {Gets warning symbol from edit control.
+    @param Symbol [out] Required symbol, trimmed of white space. Undefined if
+      not valid.
+    @return True if symbol is non-empty string, False if not.
+  }
 begin
   Symbol := Trim(edSymbol.Text);
   Result := Symbol <> '';
 end;
 
 class function TCodeGenPrefsFrame.Index: Byte;
+  {Provides an index number that determines the order in which the tabs
+  containing frames are displayed in the preferences dialog box.
+    @return Required index number.
+  }
 begin
   Result := 15;
 end;
 
 function TCodeGenPrefsFrame.IndexOfSymbolInLV(const Symbol: string): Integer;
-var
-  LI: TListItem;
+  {Gets the index of the list item containing a warning symbol in the list view.
+    @param Symbol [in] Symbol to be found.
+    @return Index of required list view item or -1 if not found.
+  }
+var
+  LI: TListItem;  // each list item in list view
 begin
   for LI in lvWarnings.Items do
   begin
@@ -399,8 +540,11 @@
 end;
 
 function TCodeGenPrefsFrame.IsValidCompilerVersion: Boolean;
-var
-  Ver: Single;
+  {Checks if compiler version entered in edit control is valid.
+    @return True if valid, False if not.
+  }
+var
+  Ver: Single;  // compiler version from edit control
 begin
   Result := GetCompilerVersion(Ver);
   if Result then
@@ -408,13 +552,20 @@
 end;
 
 function TCodeGenPrefsFrame.IsValidSymbol: Boolean;
-var
-  Symbol: string;
+  {Checks if symbol entered in edit control is valid.
+    @return True if valid, False if not.
+  }
+var
+  Symbol: string; // stores symbol: unused
 begin
   Result := GetSymbol(Symbol);
 end;
 
 procedure TCodeGenPrefsFrame.lvWarningsClick(Sender: TObject);
+  {Click event handler for warnings list view. Copies details of warning
+  associated with selected (clicked) list item to edit controls.
+    @param Sender [in] Not used.
+  }
 begin
   if not Assigned(lvWarnings.Selected) then
     Exit;
@@ -423,8 +574,10 @@
 end;
 
 procedure TCodeGenPrefsFrame.PopulateLV;
-var
-  W: TWarning;
+  {Populates list view with details of warnings.
+  }
+var
+  W: TWarning;  // references each warning
 begin
   lvWarnings.Items.BeginUpdate;
   try
@@ -437,8 +590,15 @@
 end;
 
 procedure TCodeGenPrefsFrame.PopulatePreDefCompilerMenu;
-
+  {Populates pre-defined compiler version pop-up menu with menu items.
+  }
+
+  // ---------------------------------------------------------------------------
   procedure AddMenuItem(const Compiler: string; const Ver: Single);
+    {Adds a menu item to the pop-up menu.
+      @param Compiler [in] Name of compiler (for menu item caption).
+      @param Ver [in] Version of named compiler.
+    }
   begin
     mnuPreDefCompilers.Items.Add(
       TPreDefCompilerMenuItem.Create(
@@ -446,6 +606,7 @@
       )
     );
   end;
+  // ---------------------------------------------------------------------------
 
 begin
   AddMenuItem('Delphi 6', 14.0);
@@ -458,6 +619,10 @@
 end;
 
 procedure TCodeGenPrefsFrame.PreDefCompilerMenuClick(Sender: TObject);
+  {Handler for click events on any pre-defined compiler menu item. Stores
+  required compiler version in associated edit control.
+    @param Sender [in] Reference to clicked menu item.
+  }
 begin
   edMinCompiler.Text := FormatCompilerVer(
     (Sender as TPreDefCompilerMenuItem).CompilerVer
@@ -469,6 +634,13 @@
 constructor TPreDefCompilerMenuItem.Create(AOwner: TComponent;
   const ACaption: string; const ACompilerVer: Single;
   const AClickHandler: TNotifyEvent);
+  {Constructor. Used to fully create a menu item with all required properties
+  and event handlers.
+    @param AOwner [in] Component that owns menu item.
+    @param ACaption [in] Name of compiler displayed in menu item's caption.
+    @param ACompilerVer [in] Version number of compiler named in ACaption.
+    @param AClickHandler [in] Menu item's OnClick event handler.
+  }
 begin
   inherited Create(AOwner);
   Caption := ACaption;
@@ -482,3 +654,4 @@
 TPreferencesDlg.RegisterPage(TCodeGenPrefsFrame);
 
 end.
+