fpspreadsheet: Update documentation.

git-svn-id: https://svn.code.sf.net/p/lazarus-ccr/svn@8935 8e941d3f-bd1b-0410-a28a-d453659cc2b4

components/fpspreadsheet/docs/api/source-files.txt

@@ -6,5 +6,6 @@
 ../../source/common/fpsallformats.pas
 ../../source/common/fpsrpn.pas
 ../../source/common/fpscurrency.pas
+../../source/common/fpsconditionalformat.pas
 ../../source/visual/fpspreadsheetctrls.pas
 ../../source/visual/fpspreadsheetgrid.pas

components/fpspreadsheet/examples/other/conditional_formatting/demo_conditional_formatting.pas

@@ -28,7 +28,7 @@ begin
     sh.WriteText(0, 2, 'Test values');
 
     row := 2;
-    for i := row to row+33 do
+    for i := row to row+42 do
     begin
       sh.WriteNumber(i, 2, 1.0);
       sh.WriteNumber(i, 3, 2.0);
@@ -399,6 +399,11 @@ begin
     sh.WriteText(row, 1, '3 flags');
     sh.WriteIconSet(Range(Row, 2, row, 12), is3Flags);
 
+    inc(row);
+    sh.WriteText(row, 0, 'IconSet');
+    sh.WriteText(row, 1, '5 quarters');
+    sh.WriteIconSet(Range(Row, 2, row, 12), is5Quarters);
+
     { ------ Save workbook to file-------------------------------------------- }
     dir := ExtractFilePath(ParamStr(0));
     wb.WriteToFile(dir + 'test.xlsx', true);

components/fpspreadsheet/source/common/fpsconditionalformat.pas

@@ -1,7 +1,18 @@
+{@@ ----------------------------------------------------------------------------
+  Unit **fpsConditionalFormat** implements conditional formatting for
+  Excel and OpenDocument spreadsheet documents.
+
+  AUTHORS: Werner Pamler
+
+  LICENSE: See the file COPYING.modifiedLGPL.txt, included in the Lazarus
+           distribution, for details about the license.
+-------------------------------------------------------------------------------}
+
 unit fpsConditionalFormat;
 
 {$mode objfpc}{$H+}
 {$WARN 6058 off : Call to subroutine "$1" marked as inline is not inlined}
+
 interface
 
 uses
@@ -13,7 +24,8 @@ type
     procedure Assign(ASource: TsCFRule); virtual; abstract;
   end;
 
-  { Cell is... }
+  {@@ Enumeration of the available conditions to be fulfilled by a cell value
+    in conditional formatting }
   TsCFCondition = (
     cfcEqual, cfcNotEqual,
     cfcGreaterThan, cfcLessThan, cfcGreaterEqual, cfcLessEqual,
@@ -40,6 +52,8 @@ type
     procedure Assign(ASource: TsCFRule); override;
   end;
 
+  {@@ Enumeration of the criteria to be fulfilled by the values used in
+    "color range" and "data bar" conditional formatting. }
   TsCFValueKind = (vkNone, vkMin, vkMax, vkPercent, vkPercentile, vkValue);
 
   { Color range }
@@ -72,7 +86,7 @@ type
     procedure Assign(ASource: TsCFRule); override;
   end;
 
-  { Icon sets }
+  {@@ Enumeration of the icon sets available for conditional formatting }
   TsCFIconSet = (
     is3Arrows, is3ArrowsGray, is3Flags,
     is3TrafficLights1,  // x14 in xlsx
@@ -107,7 +121,7 @@ type
     property ShowValue: Boolean read FShowValue write FShowValue;
   end;
 
-  { Rules }
+  {@@ Rule for a conditional format }
   TsCFRules = class(TFPObjectList)
   private
     function GetItem(AIndex: Integer): TsCFRule;
@@ -118,7 +132,7 @@ type
     property Priority[AIndex: Integer]: Integer read GetPriority;
   end;
 
-  { Conditional format item }
+  {@@ Conditional format item. These items are stored in an instance of TsConditionalFormatList. }
   TsConditionalFormat = class
   private
     FWorksheet: TsBasicWorksheet;
@@ -140,6 +154,7 @@ type
     property Worksheet: TsBasicWorksheet read FWorksheet;
   end;
 
+  {@@ List of conditional formats. Maintained by the workbook. }
   TsConditionalFormatList = class(TFPObjectList)
   protected
     function AddRule(ASheet: TsBasicWorksheet; ARange: TsCellRange;
@@ -202,6 +217,13 @@ uses
   Math, TypInfo,
   fpSpreadsheet;
 
+{@@ ----------------------------------------------------------------------------
+  Determines the count of icons available in the specified icon set for
+  conditional formatting.
+
+  @param    AIconSet  Icon set to be checked
+  @returns  Number of icons in the icon set.
+-------------------------------------------------------------------------------}
 function GetCFIconCount(AIconSet: TsCFIconSet): Integer;
 var
   s: String;
@@ -629,7 +651,7 @@ begin
   Result := AddRule(ASheet, ARange, rule);
 end;
 
-{ IconSet conditional format for 3 icons, ie. 2 values }
+{@@ IconSet conditional format for 3 icons, ie. 2 values }
 function TsConditionalFormatList.AddIconSetRule(ASheet: TsBasicWorksheet;
   ARange: TsCellRange; AIconSet: TsCFIconSet;
   AValueKind1: TsCFValueKind; AValue1: Double;
@@ -657,7 +679,7 @@ begin
   Result := AddRule(ASheet, ARange, rule);
 end;
 
-{ IconSet conditional format for 4 icons, i.e. 3 values }
+{@@ IconSet conditional format for 4 icons, i.e. 3 values }
 function TsConditionalFormatList.AddIconSetRule(ASheet: TsBasicWorksheet;
   ARange: TsCellRange; AIconSet: TsCFIconSet;
   AValueKind1: TsCFValueKind; AValue1: Double;
@@ -687,7 +709,7 @@ begin
   Result := AddRule(ASheet, ARange, rule);
 end;
 
-{ Iconset conditional format for 5 icons, i.e. 4 values }
+{@@ Iconset conditional format for 5 icons, i.e. 4 values }
 function TsConditionalFormatList.AddIconSetRule(ASheet: TsBasicWorksheet;
   ARange: TsCellRange; AIconSet: TsCFIconSet;
   AValueKind1: TsCFValueKind; AValue1: Double; AValueKind2: TsCFValueKind; AValue2: Double;

components/fpspreadsheet/source/common/fpspreadsheet.pas

@@ -3015,7 +3015,6 @@ begin
     Result := Workbook.GetDefaultFont;
 end;
 
-
 {@@ ----------------------------------------------------------------------------
   Returns @true if the worksheet does not contain any cell, column or row records
 -------------------------------------------------------------------------------}
@@ -3278,9 +3277,6 @@ begin
   begin
     AFormula^.Col := ACell^.Col;
     AFormula^.Row := ACell^.Row;
-
-//    ACell^.ContentType := cctFormula;
-
     ACell^.Flags := ACell^.Flags + [cfHasFormula];
     if (AFormula^.Parser <> nil) and AFormula^.Parser.Has3DLinks then
       ACell^.Flags := ACell^.Flags + [cf3dFormula];
@@ -3288,9 +3284,14 @@ begin
     DeleteFormula(ACell);
 end;
 
+{@@ ----------------------------------------------------------------------------
+  Assigns a hyperlink to an image. The image is specified by its index in the
+  internal image list
 
-{@@ Assigns a hyperlink to an image. The image is specified by its index in the
+  @param  AImageIndex  Specifies the index of the image in the internal image list.
-  internal image list}
+  @param  ATarget      Link target
+  @param  AToolTip     Optional text to be displayed as mouse-over popup
+-------------------------------------------------------------------------------}
 procedure TsWorksheet.AddHyperlinkToImage(AImageIndex: Integer; ATarget: String;
   AToolTip: String = '');
 var
@@ -3303,7 +3304,6 @@ begin
   end;
 end;
 
-
 {@@ ----------------------------------------------------------------------------
   Removes a cell from its tree container. DOES NOT RELEASE ITS MEMORY!
 
@@ -3761,7 +3761,6 @@ begin
   ClearSelection;
 end;
 
-
 {@@ ----------------------------------------------------------------------------
   Returns the list of selected cell ranges
 -------------------------------------------------------------------------------}
@@ -3883,11 +3882,10 @@ begin
   if Assigned(FOnZoom) then FOnZoom(Self);
 end;
 
-
 {@@ ----------------------------------------------------------------------------
   Writes UTF-8 encoded text to a cell.
 
-  On formats that don't support unicode, the text will be converted
+  On file formats that don't support unicode, the text will be converted
   to ISO Latin 1.
 
   @param  ARow             The row of the cell
@@ -3977,17 +3975,17 @@ begin
 end;
 
 {@@ ----------------------------------------------------------------------------
-  Writes text containing HTML codes to a cell. Here are the allowed HTML codes:
+  Writes text containing HTML codes to a cell. Here are the allowed HTML codes:@br
-    <b>, <strong>  ... bold text
+    @preformatted(  <b>, <strong>  ... bold text)
-    <i>, <em> ........ italic text
+    @preformatted(  <i>, <em> ........ italic text)
-    <u>, <ins> ....... underlined text
+    @preformatted(  <u>, <ins> ....... underlined text)
-    <s>, <del> ....... strike-out text
+    @preformatted(  <s>, <del> ....... strike-out text)
-    <sub> ............ subscript
+    @preformatted(  <sub> ............ subscript)
-    <sup> ............ superscript
+    @preformatted(  <sup> ............ superscript)
-    <font tags> ...... full font selection. "tags" can be:
+    @preformatted(  <font tags> ...... full font selection. "tags" can be:
                        face="..." ... font name
-                       size="..." ... font size, in pt, em, px, % (add units!)
+                       size="..." ... font size, in pt, em, px, %. Add units!
-                       color="..." .. font color (e.g. red, or #FF0000).
+                       color="..." .. font color, e.g. red, or #FF0000.)
 
   @param  ARow         The row of the cell
   @param  ACol         The column of the cell
@@ -4019,16 +4017,16 @@ end;
 
 {@@ ----------------------------------------------------------------------------
   Writes text containing HTML codes to a cell. Here are the allowed HTML codes:
-    <b>, <strong>  ... bold text
+  @preformatted(  <b>, <strong>  ... bold text)
-    <i>, <em> ........ italic text
+  @preformatted(  <i>, <em> ........ italic text)
-    <u>, <ins> ....... underlined text
+  @preformatted(  <u>, <ins> ....... underlined text)
-    <s>, <del> ....... strike-out text
+  @preformatted(  <s>, <del> ....... strike-out text)
-    <sub> ............ subscript
+  @preformatted(  <sub> ............ subscript)
-    <sup> ............ superscript
+  @preformatted(  <sup> ............ superscript)
-    <font tags> ...... full font selection. "tags" can be:
+  @preformatted(  <font tags> ...... full font selection. "tags" can be:
-                       face="..." ... font name
+                     face="..." ... font name
-                       size="..." ... font size, in pt, em, px, % (add units!)
+                     size="..." ... font size, in pt, em, px, %. Add units!
-                       color="..." .. font color (e.g. red, or #FF0000).
+                     color="..." .. font color, e.g. red, or #FF0000.)
 
   @param  ACell        Pointer to the cell
   @param  AText        The text containing the html codes
@@ -5386,6 +5384,10 @@ begin
     Result := lRow^.RowHeightType;
 end;
 
+{@@ ----------------------------------------------------------------------------
+  Returns @TRUE if the workbook contains at least one column with an individual
+  column format.
+-------------------------------------------------------------------------------}
 function TsWorksheet.HasColFormats: Boolean;
 var
   c: Integer;
@@ -5399,6 +5401,10 @@ begin
   Result := false;
 end;
 
+{@@ ----------------------------------------------------------------------------
+  Returns @TRUE if the workbook contains at least one row with an individual
+  row format.
+-------------------------------------------------------------------------------}
 function TsWorksheet.HasRowFormats: Boolean;
 var
   r: Integer;

components/fpspreadsheet/source/common/fpspreadsheet_cf.inc

@@ -76,7 +76,15 @@ end;
 
 
 {@@ ----------------------------------------------------------------------------
-  Writes the conditional format "color range"
+  Writes the conditional format "color range": The cell background in the
+  specified cell range is painted in colors according to the cell values.
+
+  The colors are varied between the given start color (at the miniumum cell value)
+  and end color (at the maximum cell value).
+
+  @param ARange      Range of the cells to be formatted
+  @param AStartColor Start color of the gradient of cell background colors corresponding to the minimum cell value in the given cell range.
+  @param AEndColor   End color of the gradient of cell background colors corresponding to the maximum cell value in the given cell range.
 -------------------------------------------------------------------------------}
 function TsWorksheet.WriteColorRange(ARange: TsCellRange;
   AStartColor, AEndColor: TsColor): Integer;
@@ -87,6 +95,18 @@ begin
 end;
 
 
+{@@ ----------------------------------------------------------------------------
+  Writes the conditional format "color range": The cell background in the
+  specified cell range is painted in colors according to the cell values.
+
+  The 3-color gradient varies between the given start color (at the minimum cell value),
+  the center color (at the median value) and the end color (at the maximum cell value).
+
+  @param  ARange       Range of the cells to be formatted
+  @param  AStartColor  Start color of the background color gradient corresponding to the minimum cell value in the given cell range.
+  @param  ACenterColor Intermediate color, corresponding to the median of the cell values.
+  @param  AEndColor    End color, corresponding to the maximum cell value.
+-------------------------------------------------------------------------------}
 function TsWorksheet.WriteColorRange(ARange: TsCellRange;
   AStartColor, ACenterColor, AEndColor: TsColor): Integer;
 begin
@@ -96,6 +116,25 @@ begin
 end;
 
 
+{@@ ----------------------------------------------------------------------------
+  Writes the conditional format "color range": The cell background in the
+  specified cell range is painted in colors according to the cell values.
+
+  The 2-color background color gradient begins at the cell value AStartValue with
+  the AStartColor and is valid for the cells fulfilling the condition AStartKind.
+  The gradient ends at the cell value AEndValue with AEndColor for the cells
+  fulfilling the condition AEndKind.
+
+  @param  ARange       Range of the cells to be formatted
+  @param  AStartColor  First color of the background color gradient
+  @param  AStartKind   Condition for the cell(s) to be painted in AStartColor
+  @param  AStartValue  Value to be used in the AStartKind condition
+  @param  AEndColor    Last color of the background color gradient
+  @param  AEndKind     Conditions for the cell(s) to be painted in AEndColor
+  @param  AEndValue    Value to be used in the AEndKind condition
+
+  @seeAlso TsCFValueKind
+-------------------------------------------------------------------------------}
 function TsWorksheet.WriteColorRange(ARange: TsCellRange;
   AStartColor: TsColor; AStartKind: TsCFValueKind; AStartValue: Double;
   AEndColor: TsColor; AEndKind: TsCFValueKind; AEndValue: Double): Integer;
@@ -107,6 +146,32 @@ begin
 end;
 
 
+{@@ ----------------------------------------------------------------------------
+  Writes the conditional format "color range"
+
+  Writes the conditional format "color range": The cell background in the
+  specified cell range is painted in colors according to the cell values.
+
+  The 3-color background color gradient begins at the cell value AStartValue with
+  the AStartColor and is valid for the cells fulfilling the condition AStartKind.
+  The ACenterColor is an intermediate color for the cell(s) fulfilling the
+  condition ACenterKind when their value is equal to ACenterValue.
+  The gradient ends at the cell value AEndValue with AEndColor for the cells
+  fulfilling the condition AEndKind.
+
+  @param  ARange       Range of the cells to be formatted
+  @param  AStartColor  First color of the background color gradient
+  @param  AStartKind   Condition for the cell(s) to be painted in AStartColor
+  @param  AStartValue  Value to be used in the AStartKind condition
+  @param  ACenterColor Intermediate color of the background color gradient
+  @param  ACenterKind  Condition for the cell(s) to be painted in ACenterColor
+  @param  ACenterValue Value to be used in the ACenterKind condition
+  @param  AEndColor    Last color of the background color gradient
+  @param  AEndKind     Conditions for the cell(s) to be painted in AEndColor
+  @param  AEndValue    Value to be used in the AEndKind condition
+
+  @seeAlso TsCFValueKind
+-------------------------------------------------------------------------------}
 function TsWorksheet.WriteColorRange(ARange: TsCellRange;
   AStartColor: TsColor; AStartKind: TsCFValueKind; AStartValue: Double;
   ACenterColor: TsColor; ACenterKind: TsCFValueKind; ACenterValue: Double;
@@ -121,16 +186,31 @@ end;
 
 
 {@@ ----------------------------------------------------------------------------
-  Writes the conditional format "data bars"
+  Writes the conditional format "data bars" in which the cell values are
+  illustrated graphically as horizontal bars.
+
+  @param  ARange     Range of the cells to be formatted
+  @param  ABarColor  Color of the bars
 -------------------------------------------------------------------------------}
-function TsWorksheet.WriteDataBars(ARange: TscellRange; ABarColor: TsColor): Integer;
+function TsWorksheet.WriteDataBars(ARange: TsCellRange; ABarColor: TsColor): Integer;
 begin
   Result := FWorkbook.FConditionalFormatList.AddDataBarRule(Self, ARange, ABarColor);
   StoreCFIndexInCells(self, Result, ARange);
 end;
 
 
-function TsWorksheet.WriteDataBars(ARange: TscellRange; ABarColor: TsColor;
+{@@ ----------------------------------------------------------------------------
+  Writes the conditional format "data bars" in which the cell values are
+  illustrated graphically as horizontal bars.
+
+  @param  ARange      Range of the cells to be formatted
+  @param  ABarColor   Color of the bars
+  @param  AStartKind  Condition to be met for the cell(s) at which the bar starts
+  @param  AStartValue Value to be used for comparison in AStartKind
+  @param  AEndKind    Condition to be met for the cell(s) at which the bar ends
+  @param  AEndValue   Value to be used for comparison in AEndKind
+-------------------------------------------------------------------------------}
+function TsWorksheet.WriteDataBars(ARange: TsCellRange; ABarColor: TsColor;
   AStartKind: TsCFValueKind; AStartValue: Double;
   AEndKind: TsCFValueKind; AEndValue: Double): Integer;
 begin
@@ -144,9 +224,16 @@ end;
 
 
 {@@ ----------------------------------------------------------------------------
-  Writes the conditional format "icon set"
+  Writes the conditional format "icon set" in which cell values are illustrated
--------------------------------------------------------------------------------}
+  by means of icons.
 
+  @param  ARange     Range of the cells to be formatted
+  @param  AIconSet   Selection of the icon set to be used.
+  @param  AHideText  Hides the normal cell text
+  @param  AReverse   Icons are assigned in reverse order.
+
+  @seeAlso  TsCFIconSet
+-------------------------------------------------------------------------------}
 function TsWorksheet.WriteIconSet(ARange: TsCellRange; AIconSet: TsCFIconSet;
   AHideText: Boolean = false; AReverse: Boolean = false): Integer;
 begin
@@ -156,6 +243,22 @@ begin
   StoreCFIndexInCells(self, Result, ARange);
 end;
 
+{@@ ----------------------------------------------------------------------------
+  Writes the conditional format "icon set" in which cell values are illustrated
+  by means of three icons.
+
+  @param  ARange       Range of the cells to be formatted
+  @param  AIconSet     Selection of the icon set to be used.
+  @param  AValueKind1  Condition for the cell values to be displayed with the first icon in the icon set
+  @param  AValue1      Value to be compared with in the AValueKind1 condition
+  @param  AValueKind2  Condition for the cell values to be displayed with the second icon in the icon set
+  @param  AValue2      Value to be compared with in the AValueKind2 condition
+  @param  AHideText    Hides the normal cell text
+  @param  AReverse     Icons are assigned in reverse order.
+
+  @seeAlso  TsCFIconSet
+  @seeAlso  TsCFValueKind
+-------------------------------------------------------------------------------}
 function TsWorksheet.WriteIconSet(ARange: TsCellRange; AIconSet: TsCFIconSet;
   AValueKind1: TsCFValueKind; AValue1: Double;
   AValueKind2: TsCFValueKind; AValue2: Double;
@@ -171,6 +274,24 @@ begin
     StoreCFIndexInCells(self, Result, ARange);
 end;
 
+{@@ ----------------------------------------------------------------------------
+  Writes the conditional format "icon set" in which cell values are illustrated
+  by means of four icons.
+
+  @param  ARange       Range of the cells to be formatted
+  @param  AIconSet     Selection of the icon set to be used.
+  @param  AValueKind1  Condition for the cell values to be displayed with the first icon in the icon set
+  @param  AValue1      Value to be compared with in the AValueKind1 condition
+  @param  AValueKind2  Condition for the cell values to be displayed with the second icon in the icon set
+  @param  AValue2      Value to be compared with in the AValueKind2 condition
+  @param  AValueKind3  Condition for the cell values to be displayed with the third icon in the icon set
+  @param  AValue3      Value to be compared with in the AValueKind3 condition
+  @param  AHideText    Hides the normal cell text
+  @param  AReverse     Icons are assigned in reverse order.
+
+  @seeAlso  TsCFIconSet
+  @seeAlso  TsCFValueKind
+-------------------------------------------------------------------------------}
 function TsWorksheet.WriteIconSet(ARange: TsCellRange; AIconSet: TsCFIconSet;
   AValueKind1: TsCFValueKind; AValue1: Double;
   AValueKind2: TsCFValueKind; AValue2: Double;
@@ -188,6 +309,27 @@ begin
     StoreCFIndexInCells(self, Result, ARange);
 end;
 
+
+{@@ ----------------------------------------------------------------------------
+  Writes the conditional format "icon set" in which cell values are illustrated
+  by means of five icons.
+
+  @param  ARange       Range of the cells to be formatted
+  @param  AIconSet     Selection of the icon set to be used.
+  @param  AValueKind1  Condition for the cell values to be displayed with the first icon in the icon set
+  @param  AValue1      Value to be compared with in the AValueKind1 condition
+  @param  AValueKind2  Condition for the cell values to be displayed with the second icon in the icon set
+  @param  AValue2      Value to be compared with in the AValueKind2 condition
+  @param  AValueKind3  Condition for the cell values to be displayed with the third icon in the icon set
+  @param  AValue3      Value to be compared with in the AValueKind3 condition
+  @param  AValueKind4  Condition for the cell values to be displayed with the fourth icon in the icon set
+  @param  AValue4      Value to be compared with in the AValueKind4 condition
+  @param  AHideText    Hides the normal cell text
+  @param  AReverse     Icons are assigned in reverse order.
+
+  @seeAlso  TsCFIconSet
+  @seeAlso  TsCFValueKind
+-------------------------------------------------------------------------------}
 function TsWorksheet.WriteIconSet(ARange: TsCellRange; AIconSet: TsCFIconSet;
   AValueKind1: TsCFValueKind; AValue1: Double;
   AValueKind2: TsCFValueKind; AValue2: Double;
@@ -213,12 +355,18 @@ end;
 {   TsWorkbook code for conditional formats                                    }
 {==============================================================================}
 
+{@@ ----------------------------------------------------------------------------
+  Returns the conditional format record at the specified index in the workbook's
+  conditional format list.
+-------------------------------------------------------------------------------}
 function TsWorkbook.GetConditionalFormat(AIndex: Integer): TsConditionalFormat;
 begin
   Result := FConditionalFormatList[AIndex] as TsConditionalFormat;
 end;
 
-
+{@@ ----------------------------------------------------------------------------
+  Returns the count of conditional formats available in the the workbook.
+-------------------------------------------------------------------------------}
 function TsWorkbook.GetNumConditionalFormats: Integer;
 begin
   Result := FConditionalFormatList.Count;

components/fpspreadsheet/source/common/fpspreadsheet_embobj.inc

@@ -198,7 +198,11 @@ begin
   Result := FImages.Count;
 end;
 
+{@@ ----------------------------------------------------------------------------
+  Returns a pointer to the image record at the specified index.
 
+  @param  AIndex   Index of the image to be considered.
+-------------------------------------------------------------------------------}
 function TsWorksheet.GetPointerToImage(AIndex: Integer): PsImage;
 begin
   Result := PsImage(FImages[AIndex]);

components/fpspreadsheet/source/common/fpspreadsheet_fmt.inc

@@ -136,7 +136,7 @@ begin
 end;
 
 {@@ ----------------------------------------------------------------------------
-  Determines which the style of a particular cell border
+  Determines the style of a particular cell border
 -------------------------------------------------------------------------------}
 function TsWorksheet.ReadCellBorderStyle(ACell: PCell;
   ABorder: TsCelLBorder): TsCellBorderStyle;
@@ -152,7 +152,7 @@ begin
 end;
 
 {@@ ----------------------------------------------------------------------------
-  Determines which all border styles of a given cell
+  Determines all border styles of a given cell
 -------------------------------------------------------------------------------}
 function TsWorksheet.ReadCellBorderStyles(ACell: PCell): TsCellBorderStyles;
 var
@@ -166,7 +166,6 @@ begin
   end;
 end;
 
-
 {@@ ----------------------------------------------------------------------------
   Returns the format record that is assigned to a specified cell
 -------------------------------------------------------------------------------}
@@ -175,7 +174,6 @@ begin
   Result := Workbook.GetCellFormat(ACell^.FormatIndex);
 end;
 
-
 {@@ ----------------------------------------------------------------------------
   Returns the protection flags of the cell.
 
@@ -716,7 +714,12 @@ begin
   WriteCellProtection(Result, AValue);
 end;
 
+{@@ ----------------------------------------------------------------------------
+  Defines how the specified cell is protected: lock cell modification and/or hide formulas.
+  Note that this is activated only after enabling worksheet protection (worksheet.Protect(true)).
 
+  @NOTE FPSpreadsheet does not enforce these actions. They are only written to the file for the Office application.
+-------------------------------------------------------------------------------}
 procedure TsWorksheet.WriteCellProtection(ACell: PCell;
   AValue: TsCellProtections);
 var