View Issue Details

IDProjectCategoryView StatusLast Update
0038000LazarusDocumentationpublic2020-10-29 18:10
ReporterDon Siders Assigned ToJuha Manninen  
PrioritynormalSeverityminorReproducibilityN/A
Status closedResolutionfixed 
Product Version2.1 (SVN) 
Summary0038000: Documentation updates for LCL, LazUtils
DescriptionMinor updates. See attached.

TagsNo tags attached.
Fixed in Revisionr64082
LazTarget-
Widgetset
Attached Files

Activities

Don Siders

2020-10-28 03:30

reporter  

docs-lcl.diff (1,574 bytes)   
Index: docs/xml/lcl/printers.xml
===================================================================
--- docs/xml/lcl/printers.xml	(revision 64078)
+++ docs/xml/lcl/printers.xml	(working copy)
@@ -2324,7 +2324,7 @@
             BeginDoc calls <var>SelectCurrentPrinterOrDefault</var> to ensure a valid printer is selected for the class instance. If the current selection is invalid, the "default" printer is selected. The default printer is the first one in Printers.
           </p>
           <p>
-            BeginDoc updates <var>PrinterFlags</var> to include the value <var>pfPrinting</var>, and removes the value <var>pfAborted</var> (if present). The <var>PageNumber</var> property is set to <b>1</b> (<b>one</b>) for the newly started printing operation.
+            BeginDoc updates <var>PrinterFlags</var> to include the value <var>pfPrinting</var>, and removes the value <var>pfAborted</var> (if present). The <var>PageNumber</var> property is reset for the newly started printing operation.
           </p>
           <p>
             BeginDoc uses the value in <var>RawMode</var> to determine if a printer canvas is in used for the class instance. When RawMode is <b>False</b>, a <var>TPrinterCanvas</var> instance exists in <var>Canvas</var>. Its <var>Refresh</var> method is called, and the <var>BeginDoc</var> method in the printer canvas is called to synchronize the canvas. The value in <var>YDPI</var> is assigned to the PPI (Pixels per Inch) setting for the canvas font. No actions are performed for the printer canvas when RawMode is <b>True</b>.
docs-lcl.diff (1,574 bytes)   
docs-lazutils.diff (84,911 bytes)   
Index: docs/xml/lazutils/lazutf8.xml
===================================================================
--- docs/xml/lazutils/lazutf8.xml	(revision 64078)
+++ docs/xml/lazutils/lazutf8.xml	(working copy)
@@ -11,7 +11,7 @@
         Routines for managing UTF-8-encoded strings
       </short>
       <descr>
-        lazutf.pas contains useful routines for managing UTF-8-encoded strings. All routines are thread-safe unless explicitly stated.
+        <file>lazutf8.pas</file> contains useful routines for managing UTF-8-encoded strings. All routines are thread-safe unless explicitly stated.
       </descr>
 
       <!-- unresolved externals -->
@@ -1707,7 +1707,7 @@
             <dd>Value S1 comes after S2 but the comparison ended at a different byte in an invalid UTF-8 codepoint</dd>
           </dl>
           <p>
-            Internally, UTF8CompareStr uses WideCompareStr on the first UTF-8 codepoint that differs between S1 and S2. As a result, it has proper collation on platforms where the WidestringManager supports this (Windows, *nix with cwstring unit).
+            Internally, UTF8CompareStr uses WideCompareStr on the first UTF-8 codepoint that differs between S1 and S2. As a result, it has proper collation on platforms where the WidestringManager supports this (Windows, *nix with <file>cwstring</file> unit).
           </p>
         </descr>
         <seealso></seealso>
@@ -2169,7 +2169,7 @@
         </short>
         <descr>
           <p>
-            FPUpChars is an array of char type with the Lower and Upper bounds permitted for the char type. Values in FPUpChars are assigned in the initialization section for the lazutf8.pas unit, and contains the upper case equivalent for all characters in the char type.
+            FPUpChars is an array of char type with the Lower and Upper bounds permitted for the char type. Values in FPUpChars are assigned in the initialization section for the <file>lazutf8.pas</file> unit, and contains the upper case equivalent for all characters in the char type.
           </p>
         </descr>
         <seealso></seealso>
Index: docs/xml/lazutils/lconvencoding.xml
===================================================================
--- docs/xml/lazutils/lconvencoding.xml	(revision 64078)
+++ docs/xml/lazutils/lconvencoding.xml	(working copy)
@@ -29,231 +29,213 @@
       <element name="iconvenc"/>
 
       <element name="TConvertEncodingErrorMode">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Represents the behaviors for an error occurring in an encoding conversion</short>
+        <descr>
+          <p>
+            <var>TConvertEncodingErrorMode</var> is an enumerated type with values that represent the behavior applied when an encoding conversion error is detected. TConvertEncodingErrorMode is the type used for the <var>ConvertEncodingErrorMode</var> variable.
+          </p>
+        </descr>
+        <seealso>
+          <link id="ConvertEncodingErrorMode"/>
+        </seealso>
       </element>
       <element name="TConvertEncodingErrorMode.ceemSkip">
-        <short/>
+        <short>Skip or ignore the encoding conversion error</short>
       </element>
       <element name="TConvertEncodingErrorMode.ceemException">
-        <short/>
+        <short>Raise an EConvertError exception with a message releveant to the concersion error</short>
       </element>
       <element name="TConvertEncodingErrorMode.ceemReplace">
-        <short/>
+        <short>Replace the suspect value with an error placeholder (usually the '?' character)</short>
       </element>
       <element name="TConvertEncodingErrorMode.ceemReturnEmpty">
-        <short/>
+        <short>Return an empty string ('') for the suspect value</short>
       </element>
 
       <element name="ConvertEncodingErrorMode">
-        <short/>
+        <short>Error handling behavior for encoding conversion errors</short>
         <descr>
           <p>
-            Global variable which controls the behaviour of encoding conversion errors for the following:
+            <var>ConvertEncodingErrorMode</var> is a unit global <var>TConvertEncodingErrorMode</var> variable which controls the behaviour of encoding conversion errors for the following:
           </p>
           <ul>
-            <li>UTF8 to single byte encoding</li>
-            <li>DBCS (Asian) encoding to UTF8</li>
-            <li>UTF8 to DBCS</li>
+            <li>UTF-8 to single byte encoding</li>
+            <li>DBCS (Asian) encoding to UTF-8</li>
+            <li>UTF-8 to DBCS</li>
           </ul>
+          <p>
+            The default value for the variable is <var>ceemSkip</var>, and indicates that an error is skipped or ignored when encountered in an encoding conversion.
+          </p>
         </descr>
-        <seealso/>
+        <seealso>
+          <link id="TConvertEncodingErrorMode"/>
+          <link id="UTF8ToSingleByte"/>
+          <link id="CodepagesAsian.DBCSToUTF8"/>
+          <link id="CodepagesAsian.UTF8ToDBCS"/>
+          <link id="CodepagesAsian.UnicodeToCP936"/>
+        </seealso>
       </element>
 
       <element name="EncodingUTF8">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for UTF-8</short>
       </element>
       <element name="EncodingAnsi">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for ANSI</short>
       </element>
       <element name="EncodingUTF8BOM">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for UTF-8 with a byte order mark</short>
       </element>
       <element name="EncodingUCS2LE">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for UCS 2-byte Little Endian</short>
       </element>
       <element name="EncodingUCS2BE">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for UCS 2-byte Big Endian</short>
       </element>
       <element name="EncodingCP1250">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 1250</short>
       </element>
       <element name="EncodingCP1251">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 1251</short>
       </element>
       <element name="EncodingCP1252">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 1252</short>
       </element>
       <element name="EncodingCP1253">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 1253</short>
       </element>
       <element name="EncodingCP1254">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 1254</short>
       </element>
       <element name="EncodingCP1255">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 1255</short>
       </element>
       <element name="EncodingCP1256">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 1256</short>
       </element>
       <element name="EncodingCP1257">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 1257</short>
       </element>
       <element name="EncodingCP1258">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 1258</short>
       </element>
       <element name="EncodingCP437">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 437</short>
       </element>
       <element name="EncodingCP850">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 850</short>
       </element>
       <element name="EncodingCP852">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 852</short>
       </element>
       <element name="EncodingCP866">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 866</short>
       </element>
       <element name="EncodingCP874">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 874</short>
       </element>
       <element name="EncodingCP932">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 932</short>
       </element>
       <element name="EncodingCP936">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 936</short>
       </element>
       <element name="EncodingCP949">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 949</short>
       </element>
       <element name="EncodingCP950">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for Code Page 950</short>
       </element>
       <element name="EncodingCPMac">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for the Macintosh Code Page</short>
       </element>
       <element name="EncodingCPKOI8R">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for KOI-8R Code Page</short>
       </element>
       <element name="EncodingCPKOI8U">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for KOI-8U Code Page</short>
       </element>
       <element name="EncodingCPKOI8RU">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for KOI-8RU Code Page</short>
       </element>
       <element name="EncodingCPIso1">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for ISO 8859-1 Code Page</short>
       </element>
       <element name="EncodingCPIso2">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for ISO 8859-2 Code Page</short>
       </element>
       <element name="EncodingCPIso15">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Encoding name for ISO 8859-15 Code Page</short>
       </element>
 
       <element name="UTF8BOM">
-        <short/>
+        <short>ANSI representation for the UTF-8 Byte Order Mark</short>
         <descr/>
         <seealso/>
       </element>
       <element name="UTF16BEBOM">
-        <short/>
+        <short>ANSI representation for the UTF-16 Big Endian Byte Order Mark</short>
         <descr/>
         <seealso/>
       </element>
       <element name="UTF16LEBOM">
-        <short/>
+        <short>ANSI representation for the UTF-16 Little Endian Byte Order Mark</short>
         <descr/>
         <seealso/>
       </element>
       <element name="UTF32BEBOM">
-        <short/>
+        <short>ANSI representation for the UTF-32 Big Endian Byte Order Mark</short>
         <descr/>
         <seealso/>
       </element>
       <element name="UTF32LEBOM">
-        <short/>
+        <short>ANSI representation for the UTF-32 Little Endian Byte Order Mark</short>
         <descr/>
         <seealso/>
       </element>
 
       <element name="GuessEncoding">
-        <short/>
-        <descr/>
+        <short>Tries to determine the encoding used for the specified value</short>
+        <descr>
+          <p>
+            <var>GuessEncoding</var> is a <var>String</var> function which tries to determine the encoding used for the value specified in <var>S</var>. The return value contains an encoding name, like 'utf8' or 'ISO-8859-1'. It may contain an empty string ('') when S is also an empty string.
+          </p>
+          <p>
+            GuessEncoding checks S for various Byte Order Marks at the start of the value, including: <var>UTF8BOM</var>, <var>UTF16LEBOM</var>, and <var>UTF16BEBOM</var>. When present, the BOM determines the encoding used for the value.
+          </p>
+          <p>
+            Next, it checks for an explict '<b>{%encoding </b>' marker at the start of the value. When present, the value after the marker (up to the closing '<b>}</b>' character) is normalized and used as the return value.
+          </p>
+          <p>
+            Finally, it checks for a valid UTF-8 encoding (which includes ASII characters).
+            All characters in S are examined until a character whose UTF-8 code point is not valid is encountered.
+          </p>
+          <p>
+            When <var>EncodingValid</var> is <b>True</b>, <var>EncodingAnsi</var> is assumed. Otherwise, the default encoding for the platform is used. When the return value is <var>EncodingUTF8</var>, it is changed to '<b>ISO-8859-1</b>'. This is done because the system may use the UTF-8 encoding, but the value in S does not. ISO 8859-1 has a full mapping to Unicode, and this prevents data loss in encoding conversions.
+          </p>
+        </descr>
         <seealso/>
+        <notes>
+          <note>!!! This needs review for accuracy.</note>
+        </notes>
       </element>
       <element name="GuessEncoding.Result">
-        <short/>
+        <short>Encoding name detected, or a default value</short>
       </element>
       <element name="GuessEncoding.s">
-        <short/>
+        <short>String with the content examined in the routine</short>
       </element>
 
       <element name="ConvertEncodingFromUTF8">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Converts the encoded value from UTF-8 to the specified encoding</short>
+        <descr>
+          <p>
+            Used in the implementation of the ConvertEncoding function.
+          </p>
+        </descr>
+        <seealso>
+          <link id="ConvertEncoding"/>
+          <link id="ConvertEncodingToUTF8"/>
+        </seealso>
       </element>
       <element name="ConvertEncodingFromUTF8.Result">
         <short/>
@@ -272,9 +254,16 @@
       </element>
 
       <element name="ConvertEncodingToUTF8">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Converts the specified value to the UTF-8 encoding</short>
+        <descr>
+          <p>
+            Used in the implementation of the ConvertEncoding function.
+          </p>
+        </descr>
+        <seealso>
+          <link id="ConvertEncoding"/>
+          <link id="ConvertEncodingFromUTF8"/>
+        </seealso>
       </element>
       <element name="ConvertEncodingToUTF8.Result">
         <short/>
@@ -290,7 +279,7 @@
       </element>
 
       <element name="ConvertEncoding">
-        <short/>
+        <short>Converts the encoding for a value from its source encoding to the target encoding</short>
         <descr/>
         <seealso/>
       </element>
@@ -322,10 +311,10 @@
       </element>
 
       <element name="GetConsoleTextEncoding">
-        <short/>
+        <short>Gets the encoding used in a console on the platform</short>
         <descr>
           <p>
-            This routine returns the console text encoding, which might be different from the normal system encoding in some Windows systems. See
+            This routine returns the console text encoding, which might be different from the normal system encoding on some Windows systems. See
             <url href="http://mantis.freepascal.org/view.php?id=20552">http://mantis.freepascal.org/view.php?id=20552</url>
           </p>
         </descr>
@@ -336,7 +325,7 @@
       </element>
 
       <element name="NormalizeEncoding">
-        <short/>
+        <short>Converts the specified encoding name to lowercase and removes '-' characters</short>
         <descr/>
         <seealso/>
       </element>
@@ -348,15 +337,21 @@
       </element>
 
       <element name="TConvertEncodingFunction">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Specifies a function used to convert the encoding for a string value</short>
+        <descr>
+          <p>
+            <var>TConvertEncodingFunction</var> is the type used for the <var>ConvertAnsiToUTF8</var>  variable.
+          </p>
+        </descr>
+        <seealso>
+          <link id="ConvertAnsiToUTF8"/>
+        </seealso>
       </element>
       <element name="TConvertEncodingFunction.Result">
-        <short/>
+        <short>Value after converting the value to the required encoding</short>
       </element>
       <element name="TConvertEncodingFunction.s">
-        <short/>
+        <short>Value examined and converted in the routine</short>
       </element>
 
       <element name="TConvertUTF8ToEncodingFunc">
@@ -375,7 +370,7 @@
       </element>
 
       <element name="TCharToUTF8Table">
-        <short/>
+        <short>Alias for the TCharToUTF8Table type in CodepagesCommon</short>
         <descr/>
         <seealso/>
       </element>
@@ -393,19 +388,25 @@
       </element>
 
       <element name="ConvertAnsiToUTF8">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Routine used to convert from ANSI to UTF-8 encoding</short>
+        <descr>
+          <p>
+            <var>ConvertAnsiToUTF8</var> is a <var>TConvertEncodingFunction</var> variable provides a routine used to convert a String value from its ANSI-encoded value to the UTF-8 encoding.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TConvertEncodingFunction"/>
+        </seealso>
       </element>
 
       <element name="ConvertUTF8ToAnsi">
-        <short/>
+        <short>Routine used to convert from UTF-8 to ANSI encoding</short>
         <descr/>
         <seealso/>
       </element>
 
       <element name="UTF8BOMToUTF8">
-        <short/>
+        <short>Removes the UTF-8 BOM from the UTF-8 encoded value</short>
         <descr/>
         <seealso/>
       </element>
@@ -417,7 +418,7 @@
       </element>
 
       <element name="ISO_8859_1ToUTF8">
-        <short/>
+        <short>Converts an ISO 8859-1-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -429,7 +430,7 @@
       </element>
 
       <element name="ISO_8859_2ToUTF8">
-        <short/>
+        <short>Converts an ISO 8859-2-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -441,7 +442,7 @@
       </element>
 
       <element name="CP1250ToUTF8">
-        <short/>
+        <short>Converts a Code Page 1250-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -453,7 +454,7 @@
       </element>
 
       <element name="CP1251ToUTF8">
-        <short/>
+        <short>Converts a Code Page 1251-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -465,7 +466,7 @@
       </element>
 
       <element name="CP1252ToUTF8">
-        <short/>
+        <short>Converts a Code Page 1252-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -477,7 +478,7 @@
       </element>
 
       <element name="CP1253ToUTF8">
-        <short/>
+        <short>Converts a Code Page 1253-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -489,7 +490,7 @@
       </element>
 
       <element name="CP1254ToUTF8">
-        <short/>
+        <short>Converts a Code Page 1254-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -501,7 +502,7 @@
       </element>
 
       <element name="CP1255ToUTF8">
-        <short/>
+        <short>Converts a Code Page 1255-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -513,7 +514,7 @@
       </element>
 
       <element name="CP1256ToUTF8">
-        <short/>
+        <short>Converts a Code Page 1256-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -525,7 +526,7 @@
       </element>
 
       <element name="CP1257ToUTF8">
-        <short/>
+        <short>Converts a Code Page 1257-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -537,7 +538,7 @@
       </element>
 
       <element name="CP1258ToUTF8">
-        <short/>
+        <short>Converts a Code Page 1258-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -549,7 +550,7 @@
       </element>
 
       <element name="CP437ToUTF8">
-        <short/>
+        <short>Converts a Code Page 437-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -561,7 +562,7 @@
       </element>
 
       <element name="CP850ToUTF8">
-        <short/>
+        <short>Converts a Code Page 850-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -573,7 +574,7 @@
       </element>
 
       <element name="CP852ToUTF8">
-        <short/>
+        <short>Converts a Code Page 852-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -585,7 +586,7 @@
       </element>
 
       <element name="CP866ToUTF8">
-        <short/>
+        <short>Converts a Code Page 866-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -597,7 +598,7 @@
       </element>
 
       <element name="CP874ToUTF8">
-        <short/>
+        <short>Converts a Code Page 874-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -609,7 +610,7 @@
       </element>
 
       <element name="KOI8RToUTF8">
-        <short/>
+        <short>Converts a KOI-8R-encoded value to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -621,7 +622,7 @@
       </element>
 
       <element name="MacintoshToUTF8">
-        <short/>
+        <short>Converts a value encoded using the the Macintosh Code Page to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -633,22 +634,41 @@
       </element>
 
       <element name="SingleByteToUTF8">
-        <short/>
+        <short>Converts a string with single-byte values to UTF-8 using a character mapping table</short>
         <descr/>
-        <seealso/>
+        <seealso>
+          <link id="CharToUTF8Table"/>
+          <link id="#lazutils.CodePagesCommon.ArrayISO_8859_1ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayISO_8859_15ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayISO_8859_2ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP1250ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP1251ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP1252ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP1253ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP1254ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP1255ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP1255ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP1257ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP437ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP850ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayCP866ToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayKOI8RToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayKOI8UToUTF8"/>
+          <link id="#lazutils.CodePagesCommon.ArrayMacintoshUToUTF8"/>
+        </seealso>
       </element>
       <element name="SingleByteToUTF8.Result">
-        <short/>
+        <short>String with the UTF-8-encoded value, or an empty string</short>
       </element>
       <element name="SingleByteToUTF8.s">
-        <short/>
+        <short>String with the siobngle-byte values converted in the routine</short>
       </element>
       <element name="SingleByteToUTF8.Table">
-        <short/>
+        <short>Table with Character to PChar mappings for the converted value</short>
       </element>
 
       <element name="UCS2LEToUTF8">
-        <short/>
+        <short>Converts a value in UCS 2-byte LE encoding to UTF8</short>
         <descr/>
         <seealso/>
       </element>
@@ -660,7 +680,7 @@
       </element>
 
       <element name="UCS2BEToUTF8">
-        <short/>
+        <short>Converts a value in UCS 2-byte BE encoding to UTF8</short>
         <descr/>
         <seealso/>
       </element>
@@ -672,7 +692,7 @@
       </element>
 
       <element name="UTF8ToUTF8BOM">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to UTF-8 with a Byte Order Mark</short>
         <descr/>
         <seealso/>
       </element>
@@ -684,7 +704,7 @@
       </element>
 
       <element name="UTF8ToISO_8859_1">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to ISO 8859-1</short>
         <descr/>
         <seealso/>
       </element>
@@ -699,7 +719,7 @@
       </element>
 
       <element name="UTF8ToISO_8859_2">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to ISO 8859-2</short>
         <descr/>
         <seealso/>
       </element>
@@ -714,7 +734,7 @@
       </element>
 
       <element name="UTF8ToCP1250">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 1250</short>
         <descr/>
         <seealso/>
       </element>
@@ -729,7 +749,7 @@
       </element>
 
       <element name="UTF8ToCP1251">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 1251</short>
         <descr/>
         <seealso/>
       </element>
@@ -744,7 +764,7 @@
       </element>
 
       <element name="UTF8ToCP1252">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 1252</short>
         <descr/>
         <seealso/>
       </element>
@@ -759,7 +779,7 @@
       </element>
 
       <element name="UTF8ToCP1253">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 1253</short>
         <descr/>
         <seealso/>
       </element>
@@ -774,7 +794,7 @@
       </element>
 
       <element name="UTF8ToCP1254">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 1254</short>
         <descr/>
         <seealso/>
       </element>
@@ -789,7 +809,7 @@
       </element>
 
       <element name="UTF8ToCP1255">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 1255</short>
         <descr/>
         <seealso/>
       </element>
@@ -804,7 +824,7 @@
       </element>
 
       <element name="UTF8ToCP1256">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 1256</short>
         <descr/>
         <seealso/>
       </element>
@@ -819,7 +839,7 @@
       </element>
 
       <element name="UTF8ToCP1257">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 1257</short>
         <descr/>
         <seealso/>
       </element>
@@ -834,7 +854,7 @@
       </element>
 
       <element name="UTF8ToCP1258">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 1258</short>
         <descr/>
         <seealso/>
       </element>
@@ -849,7 +869,7 @@
       </element>
 
       <element name="UTF8ToCP437">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 437</short>
         <descr/>
         <seealso/>
       </element>
@@ -864,7 +884,7 @@
       </element>
 
       <element name="UTF8ToCP850">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 850</short>
         <descr/>
         <seealso/>
       </element>
@@ -879,7 +899,7 @@
       </element>
 
       <element name="UTF8ToCP852">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 852</short>
         <descr/>
         <seealso/>
       </element>
@@ -894,7 +914,7 @@
       </element>
 
       <element name="UTF8ToCP866">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 866</short>
         <descr/>
         <seealso/>
       </element>
@@ -909,7 +929,7 @@
       </element>
 
       <element name="UTF8ToCP874">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to Code Page 874</short>
         <descr/>
         <seealso/>
       </element>
@@ -924,7 +944,7 @@
       </element>
 
       <element name="UTF8ToKOI8R">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to KOI-8R</short>
         <descr/>
         <seealso/>
       </element>
@@ -939,7 +959,7 @@
       </element>
 
       <element name="UTF8ToKOI8U">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to KOI-8U</short>
         <descr/>
         <seealso/>
       </element>
@@ -954,7 +974,7 @@
       </element>
 
       <element name="UTF8ToKOI8RU">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to KOI-8RU</short>
         <descr/>
         <seealso/>
       </element>
@@ -969,7 +989,7 @@
       </element>
 
       <element name="UTF8ToMacintosh">
-        <short/>
+        <short>Converts a value in UTF-8 encoding to the Macintosh Code Page</short>
         <descr/>
         <seealso/>
       </element>
@@ -984,7 +1004,9 @@
       </element>
 
       <element name="UTF8ToSingleByte">
-        <short/>
+        <short>
+          Converts a UTF-8-encoded value to a single-bye character set using a conversion function
+        </short>
         <descr/>
         <seealso/>
       </element>
@@ -999,7 +1021,7 @@
       </element>
 
       <element name="UTF8ToUCS2LE">
-        <short/>
+        <short>Converts a UTF-8-encoded value  to UCS 2-byte LE</short>
         <descr/>
         <seealso/>
       </element>
@@ -1011,7 +1033,7 @@
       </element>
 
       <element name="UTF8ToUCS2BE">
-        <short/>
+        <short>Converts a UTF-8-encoded value  to UCS 2-byte BE</short>
         <descr/>
         <seealso/>
       </element>
@@ -1023,7 +1045,7 @@
       </element>
 
       <element name="CP932ToUTF8">
-        <short/>
+        <short>Converts a value using Code Page 932 to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -1035,7 +1057,7 @@
       </element>
 
       <element name="CP936ToUTF8">
-        <short/>
+        <short>Converts a value using Code Page 936 to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -1047,7 +1069,7 @@
       </element>
 
       <element name="CP949ToUTF8">
-        <short/>
+        <short>Converts a value using Code Page 949 to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -1059,7 +1081,7 @@
       </element>
 
       <element name="CP950ToUTF8">
-        <short/>
+        <short>Converts a value using Code Page 950 to UTF-8</short>
         <descr/>
         <seealso/>
       </element>
@@ -1071,7 +1093,7 @@
       </element>
 
       <element name="UTF8ToCP932">
-        <short/>
+        <short>Converts a value using UTF-8 encoding to Code Page 932</short>
         <descr/>
         <seealso/>
       </element>
@@ -1086,7 +1108,7 @@
       </element>
 
       <element name="UTF8ToCP936">
-        <short/>
+        <short>Converts a value using UTF-8 encoding to Code Page 936</short>
         <descr/>
         <seealso/>
       </element>
@@ -1101,7 +1123,7 @@
       </element>
 
       <element name="UTF8ToCP949">
-        <short/>
+        <short>Converts a value using UTF-8 encoding to Code Page 949</short>
         <descr/>
         <seealso/>
       </element>
@@ -1116,7 +1138,7 @@
       </element>
 
       <element name="UTF8ToCP950">
-        <short/>
+        <short>Converts a value using UTF-8 encoding to Code Page 950</short>
         <descr/>
         <seealso/>
       </element>
@@ -1131,7 +1153,9 @@
       </element>
 
       <element name="UTF8ToDBCS">
-        <short/>
+        <short>
+          Converts a value from UTF-8 encoding to Double Byte Character Set encoding
+        </short>
         <descr/>
         <seealso/>
       </element>
Index: docs/xml/lazutils/masks.xml
===================================================================
--- docs/xml/lazutils/masks.xml	(revision 64078)
+++ docs/xml/lazutils/masks.xml	(working copy)
@@ -2,338 +2,892 @@
 <fpdoc-descriptions>
   <package name="lazutils">
     <!--
-  ====================================================================
-    Masks
-  ====================================================================
--->
+    ====================================================================
+      Masks
+    ====================================================================
+    -->
     <module name="Masks">
-      <short>This unit contains classes for mask matching.</short>
+      <short>Contains classes for matching file names to file masks</short>
       <descr/>
-      <!-- unresolved type reference Visibility: default -->
-      <element name="Classes">
-        <short/>
-        <descr/>
+
+      <!-- unresolved external references -->
+      <element name="Classes"/>
+      <element name="SysUtils"/>
+      <element name="Contnrs"/>
+      <element name="LazUtilsStrConsts"/>
+      <element name="LazUtf8"/>
+
+      <element name="TMaskCharType">
+        <short>Represents character types used in a mask</short>
+        <descr>
+          <p>
+            Used in the implementation of TMaskChar.
+          </p>
+        </descr>
         <seealso/>
       </element>
-      <!-- unresolved type reference Visibility: default -->
-      <element name="SysUtils">
-        <short/>
-        <descr/>
-        <seealso/>
+      <element name="TMaskCharType.mcChar">
+        <short>Represents a UTF-8-encoded character value</short>
       </element>
-      <!-- unresolved type reference Visibility: default -->
-      <element name="Contnrs">
-        <short/>
-        <descr/>
-        <seealso/>
+      <element name="TMaskCharType.mcCharSet">
+        <short>Represents a character in a set value</short>
       </element>
-      <!-- enumeration type Visibility: default -->
-      <element name="TMaskCharType">
-        <short/>
-        <descr/>
-        <seealso/>
+      <element name="TMaskCharType.mcAnyChar">
+        <short>Represents any valid single character</short>
       </element>
-      <!-- enumeration value Visibility: default -->
-      <element name="TMaskCharType.mcChar"><short/></element>
-      <!-- enumeration value Visibility: default -->
-      <element name="TMaskCharType.mcCharSet"><short/></element>
-      <!-- enumeration value Visibility: default -->
-      <element name="TMaskCharType.mcAnyChar"><short/></element>
-      <!-- enumeration value Visibility: default -->
-      <element name="TMaskCharType.mcAnyText"><short/></element>
-      <!-- enumeration value Visibility: default -->
+      <element name="TMaskCharType.mcAnyText">
+        <short>Represents any valid text</short>
+      </element>
+
       <element name="TMaskOption">
-        <short/>
+        <short>Contains options which can be enabled or disabled for TMask comparisons</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- enumeration value Visibility: default -->
-      <element name="TMaskOption.moCaseSensitive"><short>Compare case sensitive.</short></element>
-      <!-- enumeration value Visibility: default -->
-      <element name="TMaskOption.moDisableSets"><short>Disable set processing. "[" and "]" are treated as <link id="TMask">literal characters</link>.</short></element>
-      <!-- set type Visibility: default -->
-      <element name="MaskOptions">
-        <short/>
+      <element name="TMaskOption.moCaseSensitive">
+        <short>Enables case sensitive comparison</short>
+      </element>
+      <element name="TMaskOption.moDisableSets">
+        <short>
+          Disables set processing; "[" and "]" are treated as literal characters
+        </short>
+      </element>
+
+      <element name="TMaskOptions">
+        <short>Set type used to store values from the TMaskOption enumeration</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- set type Visibility: default -->
+
       <element name="TCharSet">
-        <short/>
+        <short>Defines a set for Char types</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- pointer type Visibility: default -->
+
       <element name="PCharSet">
-        <short/>
+        <short>Defines a pointer to a TCharSet type</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- record type Visibility: default -->
+
       <element name="TMaskChar">
-        <short/>
+        <short>Represent details for mask character types in  the TMaskCharType enumeration</short>
+        <descr>
+          <p>
+            <var>TMaskChar</var> is a variant record type with members used to represent details for mask character types in the <var>TMaskCharType</var> enumeration. TMaskChar is used to implement the <var>Chars</var> member in the <var>TMaskString</var> record type.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMaskCharType"/>
+          <link id="TMaskString.Chars"/>
+        </seealso>
+      </element>
+
+      <element name="TMaskChar.CharType">
+        <short>Identifies the mask character type</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- variable Visibility: default -->
+
       <element name="TMaskChar.CharValue">
-        <short/>
+        <short>UTF-8 character value for the mask character</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- variable Visibility: default -->
+
       <element name="TMaskChar.Negative">
-        <short/>
-        <descr/>
+        <short>
+          True when the "not" operator (!) is included in the character set expression in a mask
+        </short>
+          <descr/>
         <seealso/>
       </element>
-      <!-- variable Visibility: default -->
-      <element name="TMaskChar.SetValue">
-        <short/>
+
+      <element name="TMaskChar.SetValue ">
+        <short>Contains the values used in a character set expression in a mask</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- record type Visibility: default -->
+
       <element name="TMaskString">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Represent characters and symbols in a mask</short>
+        <descr>
+          <p>
+            <var>TMaskString</var> is a record type with members representing the characters or symbols in a mask, and the minimum and maximum length for the string. TMaskString is used in the implementation of methods in <var>TMask</var>.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMask.InitMaskString"/>
+          <link id="TMask.ClearMaskString"/>
+          <link id="TMask.Matches"/>
+          <link id="TMask.MatchesWindowsMask"/>
+        </seealso>
       </element>
-      <!-- variable Visibility: default -->
+
       <element name="TMaskString.MinLength">
-        <short/>
+        <short>Minimum length for a value that matches a mask</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- variable Visibility: default -->
+
       <element name="TMaskString.MaxLength">
-        <short/>
+        <short>Maximum length for a value that matches a mask</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- variable Visibility: default -->
+
       <element name="TMaskString.Chars">
-        <short/>
+        <short>Array with the TMaskChar information for a mask</short>
         <descr/>
         <seealso/>
       </element>
-      <!-- object Visibility: default -->
+
       <element name="TMask">
-        <short>The TMask class represents a mask.</short>
-        <descr><p>A mask is a compare pattern build of wildcards, sets and literal characters.</p>
-<p>Each <b>literal character</b> must match a single character in the string. Case sensitivity depends on the option <link id="TMaskOption">moCaseSensitive</link>.<br/>
-A <b>set</b> starts with "[" and ends with "]". Each element of a set is a literal character and or a range. A range is defined as first-last literal charcter. One character of a set must match a single character in the string. A set [!...] matches if the character is not in the set. The option <link id="TMaskOption">moDisableSets</link> disables set processing.<br/> 
-<b>Wildcards</b> are * and ?. An asterisk matches any number of characters. A question mark matches a single character.</p>
-<p>'Hello world' matches to the mask 'H?ll[xoy] w*d'.</p>
-</descr>  
-        <errors/>
-        <seealso/>
+        <short>The TMask class represents a mask and performs comparisons</short>
+        <descr>
+          <p>
+            A mask is a comparison pattern built using wildcards, sets and/or literal characters.
+          </p>
+          <p>
+            Each <b>literal character</b> must match a single character in the string. Case sensitivity requires the value <link id="TMaskOption">moCaseSensitive</link> in the options passed to the constructor.
+          </p>
+          <p>
+            A <b>set</b> starts with "[" and ends with "]". Each element of a set is a literal character and or a range. A range is defined as first-last literal character. One character of a set must match a single character in the string. A set [!...] matches if the character is not in the set. The option value <link id="TMaskOption">moDisableSets</link> passed to the constructor disables set processing.
+          </p>
+          <p>
+            <b>Wildcards</b> are the * and ? characters. An asterisk matches any number of characters. A question mark matches a single character.
+          </p>
+          <p>
+            For example: 'Hello world' matches to the mask 'H?ll[xoy] w*d'.
+          </p>
+        </descr>
+        <seealso>
+          <link id="MasksOverview"/>
+        </seealso>
       </element>
-      <!-- variable Visibility: private -->
-      <element name="TMask.FMask">
-        <short/>
+
+      <element name="TMask.FMask"/>
+      <element name="TMask.FInitialMask"/>
+      <element name="TMask.FOptions"/>
+
+      <element name="TMask.InitMaskString">
+        <short>
+          Initializes the mask string used in the class instance
+        </short>
+        <descr>
+          <p>
+            <var>InitMaskString</var> is a procedure used to initialize the mask string used in the class instance. <var>AValue</var> contains the mask value examined in the method.
+          </p>
+          <p>
+            InitMaskString resets values in the internal <var>TMaskString</var> instance used in the class instance. Each UTF-8 code point in AValue is examined, and the internal TMaskString is updated to reflect how the mask character is applied. For example:
+          </p>
+          <ul>
+            <li>'*' includes the value mcAnyText in the characters for the mask.</li>
+            <li>'?' includes the value mcAnyChar in the characters for the mask.</li>
+            <li>
+              '[' includes the value mcCharSet  in the characters for the mask when sets have not been disabled. Otherwise, the value mcChar is added to the characters for the mask.
+            </li>
+            <li>
+              All other values are literal characters and cause the value mcChar to be added to the characters for the mask.
+            </li>
+          </ul>
+          <p>
+            InitiMaskString is called from the <var>Create</var> constructor using the argument passed as the mask value. It is also called from the <var>MatchesWindowsMask</var> method.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMask.Create"/>
+          <link id="TMask.MatchesWindowsMask"/>
+          <link id="TMaskString"/>
+          <link id="MasksOverview"/>
+        </seealso>
+      </element>
+      <element name="TMask.InitMaskString,AValue">
+        <short>Mask value used to initialize the class instance</short>
+      </element>
+
+      <element name="TMask.ClearMaskString">
+        <short>Clears values in the internal TMaskString instance in the class</short>
         <descr/>
-        <seealso/>
+        <seealso>
+          <link id="TMaskString"/>
+        </seealso>
       </element>
-      <!-- constructor Visibility: public -->
+
       <element name="TMask.Create">
-        <short>Creates new mask for matching.</short>
-        <descr>Creates new <link id="TMask">mask</link> for matching.</descr>
-        <errors/>
-        <seealso/>
+        <short>Constructor for the class instance</short>
+        <descr>
+          <p>
+            <var>Create</var> is the overloaded constructor for the class instance. Overloaded variants are provided with parameter values that are used to configure the class instance.
+          </p>
+          <p>
+            <var>AValue</var> contain the mask value compared to a given file name in the method for the class.
+          </p>
+          <p>
+            <var>CaseSensitive</var> indicates if case sensitivity is used when comparing a file name to the mask value.
+          </p>
+          <p>
+            <var>AOptions</var> contains zero or more TMaskOption values which enable or disable features in the methods for the class instance.
+          </p>
+          <p>
+            Create calls the <var>InitMaskString</var> method to initial the internal <var>TMaskString</var> instance used in the class.
+          </p>
+          <remark>
+            Please note: The overloaded variant which does not have an AOptions parameter has been deprecated. It will be removed in a future Lazarus version.
+          </remark>
+        </descr>
+        <seealso>
+          <link id="MasksOverview"/>
+          <link id="TMaskString"/>
+          <link id="TMaskOptions"/>
+          <link id="TMaskOption"/>
+        </seealso>
       </element>
-      <!-- argument Visibility: default -->
-      <element name="TMask.Create.AValue"><short/></element>
-      <!-- destructor Visibility: public -->
+      <element name="TMask.Create.AValue">
+        <short>Mask value for the class instance</short>
+      </element>
+      <element name="TMask.Create.CaseSensitive">
+        <short>True if case sensitivity is used when comparing a file name to the mask value</short>
+      </element>
+      <element name="TMask.Create.AOptions">
+        <short>Contains options enabled or disabled in the class instance</short>
+      </element>
+
       <element name="TMask.Destroy">
-        <short/>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>Destructor for the class instance</short>
+        <descr>
+          <p>
+            <var>Destroy</var> is the overridden destructor for the class instance. Destroy call <var>ClearMaskString</var> to free resources allocated in the internal <var>TMaskString</var> instance. Destroy calls the inherited destructor prior to exiting from the method.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMask.ClearMaskString"/>
+          <link id="TMaskString"/>
+        </seealso>
       </element>
-      <!-- function Visibility: public -->
+
       <element name="TMask.Matches">
-        <short>Test if a filename matches the mask.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>Determines whether the specified file name matches the mask value</short>
+        <descr>
+          <p>
+            <var>Matches</var> is a <var>Boolean</var> function used to determine whether the specified file name matches the mask value in the class instance. Matches converts the value in <var>AFileName</var> to lowercase when case sensitivity is omitted from the <var>TMaskOptions</var> for the class instance.
+          </p>
+          <p>
+            Matches examines each of the UTF-8 code points in the AFileName argument, and compares the code points to the character types defined in the internal mask string. The return value is False when:
+          </p>
+          <ul>
+            <li>AFileName contains invalid UTF-8 code point(s).</li>
+            <li>
+              The mask has an assigned expression and AFileName does not match the minimum or maximum length for the expression.
+            </li>
+            <li>AFileName does not match the mask expression.</li>
+          </ul>
+          <p>
+            The return value is <b>True</b> when AFileName satisfies the mask expression using the options for the class instance.
+          </p>
+          <p>
+            Pass values for the mask expression and its options to the constructor for the class instance.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMask.Create"/>
+          <link id="TMaskOptions"/>
+          <link id="TMaskOption"/>
+          <link id="MasksOverview"/>
+        </seealso>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="TMask.Matches.Result"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="TMask.Matches.AFileName"><short/></element>
-      <!-- function Visibility: public -->
+      <element name="TMask.Matches.Result">
+        <short>True when the file name matches the mask in the class instance</short>
+      </element>
+      <element name="TMask.Matches.AFileName">
+        <short>File name compared to the mask value in the method</short>
+      </element>
+
       <element name="TMask.MatchesWindowsMask">
-        <short>Test if a filename matches the mask. Implements some special rules for a Windows© filesystem comparison.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>
+          Determines whether a filename matches the mask using Windows file system masks
+        </short>
+        <descr>
+          <p>
+            Determines whether a filename matches the mask value. Implements some special rules for a Windows© file system file masks and comparisons.  It is assumed that the initial mask value passed to the constructor uses Windows-specific notation, such as:
+          </p>
+          <dl>
+            <dt>foo*.*</dt>
+            <dd>
+              Matches all files starting with 'foo' regardless of the file extension. Same as  foo* using the Matches method.
+            </dd>
+            <dt>foo*.</dt>
+            <dd>Matches foo* but must not include a file extension.</dd>
+            <dt>*.</dt>
+            <dd>Matches any file name, but must not include a file extension.</dd>
+            <dt>foo.</dt>
+            <dd>Matches foo but not foo.txt.</dd>
+            <dt>foo.*</dt>
+            <dd>Matches foo, foo.txt, or foo.bar.</dd>
+            <dt>*.*</dt>
+            <dd>Matches any file name with an extension.</dd>
+          </dl>
+          <p>
+            This is done by converting the Windows-specific file mask to the equivalent notation normally used in the class instance. MatchesWindowsMask calls <var>ClearMaskString</var> and <var>InitMaskString</var> using the altered mask value, and calls the <var>Matches</var> method to perform the comparison. When a Windows-specific file mask is not found, the Matches method is called using the original mask value.
+          </p>
+          <p>
+            The return value is <b>True</b> when the value in <var>AFileName</var> satisfies the Windows-specific mask expression.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMask.Matches"/>
+          <link id="MasksOverview"/>
+        </seealso>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="TMask.MatchesWindowsMask.Result"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="TMask.MatchesWindowsMask.AFileName"><short/></element>
-      <!-- object Visibility: default -->
+      <element name="TMask.MatchesWindowsMask.Result">
+        <short>True when the file name matches the mask value in the class instance</short>
+      </element>
+      <element name="TMask.MatchesWindowsMask.AFileName">
+        <short>File name examined in the method</short>
+      </element>
+
       <element name="TParseStringList">
-        <short>The TParseStringList class is used to parse text into the list of strings.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>The TParseStringList class is used to parse text into the list of strings</short>
+        <descr>
+          <p>
+            <var>TParseStringList</var> is a <var>TStringList</var> descendant used to parse text which uses the specified line separators. An alternate constructor is introduced with parameters for the lines of text and the separators used in the class instance.
+          </p>
+          <p>
+            TParseStringList is used to get a list of file masks from a string value in the <var>TMaskList.Create</var> method.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMaskList.Create"/>
+          <link id="#rtl.classes.TStringList"/>
+        </seealso>
       </element>
-      <!-- constructor Visibility: public -->
+
       <element name="TParseStringList.Create">
-        <short>Creates new string list by parsing passed text according to separators.</short>
-        <descr/>
-        <errors/>
+        <short>Creates new string list by parsing the specified text using the separators argument</short>
+        <descr>
+          <p>
+            <var>Create</var> is constructor for the class instance. Values in the <var>AText</var> and <var>ASeparator</var> arguments determine the content stored as lines of text in the instance. AText contains one or more file mask expressions separated by one of the delimiters characters n ASeparators.
+          </p>
+          <p>
+            Each line in the string list represents a single mask value from AText.
+          </p>
+        </descr>
         <seealso/>
       </element>
-      <!-- argument Visibility: default -->
-      <element name="TParseStringList.Create.AText"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="TParseStringList.Create.ASeparators"><short/></element>
-      <!-- object Visibility: default -->
+      <element name="TParseStringList.Create.AText">
+        <short>Text examine and parsed in the method</short>
+      </element>
+      <element name="TParseStringList.Create.ASeparators">
+        <short>String with the separators used to delimit lines in the text argument</short>
+      </element>
+
       <element name="TMaskList">
-        <short>The TMaskList class represents a list of masks.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>Implements a list for masks</short>
+        <descr>
+          <p>
+            TMaskList is a class used to store a list of masks. Parameter values passed to the constructor are used to configure and populate the list of TMask instances stored in the list.
+          </p>
+          <p>
+            TMaskList is used in the implementation of the <var>MatchesMaskList</var> function.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMask"/>
+          <link id="MatchesMaskList"/>
+        </seealso>
       </element>
-      <!-- variable Visibility: private -->
-      <element name="TMaskList.FMasks">
-        <short/>
-        <descr/>
-        <seealso/>
-      </element>
-      <!-- function Visibility: private -->
+
+      <element name="TMaskList.FMasks"/>
+
       <element name="TMaskList.GetCount">
-        <short/>
+        <short>Gets the value for the Count property</short>
         <descr/>
-        <errors/>
-        <seealso/>
+        <seealso>
+          <link id="TMaskList.Count"/>
+        </seealso>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="TMaskList.GetCount.Result"><short/></element>
-      <!-- function Visibility: private -->
+      <element name="TMaskList.GetCount.Result">
+        <short>Value for the property</short>
+      </element>
+
       <element name="TMaskList.GetItem">
-        <short/>
+        <short>Gets the value for the indexed Items property</short>
         <descr/>
-        <errors/>
-        <seealso/>
+        <seealso>
+          <link id="TMaskList.Items"/>
+        </seealso>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="TMaskList.GetItem.Result"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="TMaskList.GetItem.Index"><short/></element>
-      <!-- constructor Visibility: public -->
+      <element name="TMaskList.GetItem.Result">
+        <short>Value for the property</short>
+      </element>
+      <element name="TMaskList.GetItem.Index">
+        <short>Ordinal position for the TMask instance in the property value</short>
+      </element>
+
       <element name="TMaskList.Create">
-        <short>Creates new list of masks from passed value, each item is separated by the parameter Separator.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>
+          Creates new list of masks using the specified delimited mask values and options
+        </short>
+        <descr>
+          <p>
+            <var>Create</var> is the overloaded constructor for the class instance. Create allocates resources need for the internal object list in the class instance. Arguments passed to the constructor(s) are used to configure and populate the values for the Items property.
+          </p>
+          <remark>
+            Please note: The overloaded variant which does <b>not</b> include an <var>Options</var> parameter has been <b>deprecated</b>. It will be removed in a future Lazarus version.
+          </remark>
+        </descr>
+        <seealso>
+          <link id="TMaskList.Items"/>
+          <link id="TMaskOption"/>
+          <link id="TMaskOptions"/>
+        </seealso>
       </element>
-      <!-- argument Visibility: default -->
-      <element name="TMaskList.Create.AValue"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="TMaskList.Create.ASeparator"><short/></element>
-      <!-- destructor Visibility: public -->
+      <element name="TMaskList.Create.AValue">
+        <short>Mask value(s) stored in the internal object list</short>
+      </element>
+      <element name="TMaskList.Create.ASeparator">
+        <short>Delimiter used to delimit mask values in AValue</short>
+      </element>
+      <element name="TMaskList.Create.CaseSensitive">
+        <short>Indicates if case sensitivity is used for masks</short>
+      </element>
+      <element name="TMaskList.Create.Options">
+        <short>Indicates the options enabled for the mask instances</short>
+      </element>
+
       <element name="TMaskList.Destroy">
-        <short/>
-        <descr/>
-        <errors/>
+        <short>Destructor for the class instance</short>
+        <descr>
+          <p>
+            <var>Destroy</var> is the overridden destructor for the class instance. Destroy ensures that the internal object list for the class instance is freed. Destroy calls the inherited destructor prior to exiting from the method.
+          </p>
+        </descr>
         <seealso/>
       </element>
-      <!-- function Visibility: public -->
+
       <element name="TMaskList.Matches">
-        <short>Test if the file name matches at least one of mask list items.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>Determines whether the specified file name matches a mask in the list</short>
+        <descr>
+          <p>
+            <var>Matches</var> is a <var>Boolean</var> function used to determine if the specified file name matches one of the file masks in the list.
+          </p>
+          <p>
+            <var>AFileName</var> contains the file name examined in the method.
+          </p>
+          <p>
+            Matches uses the <var>TMask</var> instances in <var>Items</var> to perform the file name comparison. Each TMask instance in Items is used to call its <var>Matches</var> method until a match is found, or until all of the masks have been visited.
+          </p>
+          <p>
+            The return value is <b>True</b> when a match is found.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMaskList.Items"/>
+          <link id="TMaskList.Count"/>
+          <link id="TMask.Matches"/>
+        </seealso>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="TMaskList.Matches.Result"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="TMaskList.Matches.AFileName"><short/></element>
-      <!-- function Visibility: public -->
+      <element name="TMaskList.Matches.Result">
+        <short>True when the file name matches one of the mask items</short>
+      </element>
+      <element name="TMaskList.Matches.AFileName">
+        <short>File name examined in the method</short>
+      </element>
+
+      <!-- g: Here -->
       <element name="TMaskList.MatchesWindowsMask">
-        <short>Test if the file name matches at least one of mask list items. Implements some special rules for a Windows© filesystem comparison.</short>
-        <descr/>
+        <short>
+          Tests whether the file name matches a mask in the list using Windows file system masks
+        </short>
+        <descr>
+          <p>
+            Tests whether the file name matches at least one of the mask items in the list. Implements some special rules for a Windows© file system comparison.
+          </p>
+        </descr>
         <errors/>
         <seealso/>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="TMaskList.MatchesWindowsMask.Result"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="TMaskList.MatchesWindowsMask.AFileName"><short/></element>
-      <!-- property Visibility: public -->
+      <element name="TMaskList.MatchesWindowsMask.Result">
+        <short>True if the file name matches one the masks in the list</short>
+      </element>
+      <element name="TMaskList.MatchesWindowsMask.AFileName">
+        <short>File name examined in the method</short>
+      </element>
+
       <element name="TMaskList.Count">
-        <short>The count of mask list items.</short>
-        <descr/>
-        <seealso/>
+        <short>The number of mask items in the list</short>
+        <descr>
+          <p>
+            <var>Count</var> is a read-only <var>Integer</var> property with the number of <var>TMask</var> instances stored in the <var>Items</var> for the list.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMaskList.Items"/>
+        </seealso>
       </element>
-      <!-- property Visibility: public -->
+
       <element name="TMaskList.Items">
-        <short>The items of mask list.</short>
-        <descr/>
-        <seealso/>
+        <short>The mask items in the list</short>
+        <descr>
+          <p>
+            <var>Items</var> is a read-only indexed <var>TMask</var> property which contains the mask instances in the list.
+          </p>
+          <p>
+            <var>Index</var> specifies the ordinal position in the list for the TMask instance accessed in the property. The property value is cast to a TMask instance when it is retrieved from the internal object list.
+          </p>
+          <p>
+            Values in the Items property are created in the Create constructor. A TMask instance is created and stored in Items for each of the mask values passed an argument to the method.
+          </p>
+          <p>
+            Use the Count property to determine the number of masks stored in Items.
+          </p>
+        </descr>
+        <seealso>
+          <link id="TMask"/>
+          <link id="TMaskList.Create"/>
+        </seealso>
       </element>
-      <!-- argument Visibility: default -->
-      <element name="TMaskList.Items.Index"><short/></element>
-      <!-- function Visibility: default -->
+      <element name="TMaskList.Items.Index">
+        <short>Ordinal position for the value in the indexed property</short>
+      </element>
+
       <element name="MatchesMask">
-        <short>Test if the file name matches the passed mask.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>Indicates whether the file name matches the specified mask</short>
+        <descr>
+          <p>
+            <var>MatchesMask</var> is an overloaded <var>Boolean</var> function used to determine if the file name specified in <var>FileName</var> matches the specified <var>Mask</var>.
+          </p>
+          <p>
+            <var>CaseSensitive</var> indicates whether case sensitivity is used when comparing the file name to the mask value.
+          </p>
+          <p>
+            <var>Options</var> contains a set of zero or more TMaskOption values enabled for the comparison. The Options argument allows enabling or disabling set notation in the mask value. Specifying <var>moDisableSets</var> in the Options parameter will disable interpreting the '<b>[</b>' character as the beginning of a set in the specified mask. Use an empty set ('<b>[]</b>') when options from the <var>TMaskOption</var> enumeration are not needed.
+          </p>
+          <p>
+            For example:
+          </p>
+          <code>MatchesMask('[x]','[x]',[moDisableSets]);  // returns True</code>
+          <p>
+            MatchesMask creates a <var>TMask</var> instance which is used to compare the file name to the mask using the specified options. Values in Mask and Options are passed as arguments the TMask constructor. The <var>Matches</var> method in the instance is called using FileName as an argument, and gets the return value for the function.
+          </p>
+          <remark>
+            Please note: The overloaded variant which does <b>not</b> include a TMaskOptions parameter has been marked as deprecated. It will be removed in a future Lazarus version.
+          </remark>
+        </descr>
+        <seealso>
+          <link id="TMask"/>
+          <link id="TMaskOption"/>
+          <link id="TMaskOptions"/>
+          <link id="MasksOverview"/>
+        </seealso>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="MatchesMask.Result"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesMask.FileName"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesMask.Mask"><short/></element>
-      <!-- function Visibility: default -->
+      <element name="MatchesMask.Result">
+        <short>True when the file name matches the mask value using the specified options</short>
+      </element>
+      <element name="MatchesMask.FileName">
+        <short>File name compared to the mask value</short>
+      </element>
+      <element name="MatchesMask.Mask">
+        <short>Mask used to perform the comparison</short>
+      </element>
+      <element name="MatchesMask.CaseSensitive">
+        <short>True when case sensitivity should be used in the comparison</short>
+      </element>
+      <element name="MatchesMask.Options">
+        <short>Set of options enabled for the comparison</short>
+      </element>
+
       <element name="MatchesWindowsMask">
-        <short>Test if the file name matches the passed mask. Implements some special rules for a Windows© filesystem comparison.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>
+          Indicates whether the file name matches the specified Windows-style file system mask
+        </short>
+        <descr>
+          <p>
+            <var>MatchesWindowsMask</var> is an overloaded <var>Boolean</var> function used to determine if the file name specified in <var>FileName</var> matches the specified <var>Mask</var>. Mask can contain a Windows-style file mask which uses the following wildcards:
+          </p>
+          <dl>
+            <dt>foo*.*</dt>
+            <dd>
+              Matches all files starting with 'foo' regardless of the file extension. Same as  foo* using the Matches method.
+            </dd>
+            <dt>foo*.</dt>
+            <dd>Matches foo* but must not include a file extension.</dd>
+            <dt>*.</dt>
+            <dd>Matches any file name, but must not include a file extension.</dd>
+            <dt>foo.</dt>
+            <dd>Matches foo but not foo.txt.</dd>
+            <dt>foo.*</dt>
+            <dd>Matches foo, foo.txt, or foo.bar.</dd>
+            <dt>*.*</dt>
+            <dd>Matches any file name with an extension.</dd>
+          </dl>
+          <p>
+            <var>CaseSensitive</var> indicates whether case sensitivity is used when comparing the file name to the mask value.
+          </p>
+          <p>
+            <var>Options</var> contains a set of zero or more TMaskOption values enabled for the comparison. The Options argument allows enabling or disabling set notation in the mask value. Specifying <var>moDisableSets</var> in the Options parameter will disable interpreting the '<b>[</b>' character as the beginning of a set in the specified mask. Use an empty set ('<b>[]</b>') when options from the <var>TMaskOption</var> enumeration are not needed.
+          </p>
+          <p>
+            For example:
+          </p>
+          <code>MatchesWindowsMask('[x]','[x]',[moDisableSets]);  // returns True</code>
+          <p>
+            MatchesWindowsMask creates a <var>TMask</var> instance which is used to compare the file name to the mask using the specified options. Values in Mask and Options are passed as arguments the TMask constructor. The <var>MatchesWindowsMask</var> method in the TMask instance is called using FileName as an argument, and gets the return value for the function.
+          </p>
+          <remark>
+            Please note: The overloaded variant which does <b>not</b> include a TMaskOptions parameter has been marked as deprecated. It will be removed in a future Lazarus version.
+          </remark>
+        </descr>
+        <seealso>
+          <link id="TMask.MatchesWindowsMask"/>
+          <link id="TMaskOption"/>
+          <link id="TMaskOptions"/>
+          <link id="MasksOverview"/>
+        </seealso>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="MatchesWindowsMask.Result"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesWindowsMask.FileName"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesWindowsMask.Mask"><short/></element>
-      <!-- function Visibility: default -->
+      <element name="MatchesWindowsMask.Result">
+        <short>True when the file name matches the mask value using the specified options</short>
+      </element>
+      <element name="MatchesWindowsMask.FileName">
+        <short>File name compared to the mask value</short>
+      </element>
+      <element name="MatchesWindowsMask.Mask">
+        <short>Mask used to perform the comparison</short>
+      </element>
+      <element name="MatchesWindowsMask.CaseSensitive">
+        <short>True when case sensitivity should be used in the comparison</short>
+      </element>
+      <element name="MatchesWindowsMask.Options">
+        <short>Set of options enabled for the comparison</short>
+      </element>
+
       <element name="MatchesMaskList">
-        <short>Test if the file name matches at least one of passed masks separated by the parameter Separator.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>
+          Determine whether the specified file name matches at least one of the specified masks
+        </short>
+        <descr>
+          <p>
+            <var>MatchesMaskList</var> is an overloaded <var>Boolean</var> function used to determine whether the specified file name matches at least one of the specified masks. MatchesMaskList is similar to <var>MatchesWindowsMaskList</var>, but uses Unix-style mask expressions. This includes use of the following:
+          </p>
+          <dl>
+            <dt>foo*</dt>
+            <dd>
+              Matches all files starting with 'foo' regardless of the file extension. Same as foo*.* using MatchesWindowsMaskList.
+            </dd>
+            <dt>foo*.</dt>
+            <dd>Matches foo* but must not include a file extension.</dd>
+            <dt>*.</dt>
+            <dd>Matches any file name, but must not include a file extension.</dd>
+            <dt>foo.</dt>
+            <dd>Matches foo but not foo.txt.</dd>
+            <dt>foo.*</dt>
+            <dd>Matches foo, foo.txt, or foo.bar.</dd>
+            <dt>*</dt>
+            <dd>Matches any file name including those with an optional extension.</dd>
+          </dl>
+          <p>
+            Overloaded variants of the routine provide arguments and configuration settings, including:
+          </p>
+          <dl>
+            <dt>Filename</dt>
+            <dd>File name compared to the file masks in Mask.</dd>
+            <dt>Mask</dt>
+            <dd>Contains one or more file mask expressions separated by one of the values in Separator.</dd>
+            <dt>Separator</dt>
+            <dd>Contains the character(s) used as a separator between mask expressions in Mask. The default separator is the SemiColon (;) character.</dd>
+            <dt>Options</dt>
+            <dd>Contains TMaskOption values which enable or disable features in the comparison. The default value is an empty set ([]).</dd>
+            <dt>CaseSensitive</dt>
+            <dd>Indicates whether the file name to mask comparison is case sensitive.</dd>
+          </dl>
+          <remark>
+            Please note: The overloaded variant which includes the <var>CaseSensitive</var> argument has been deprecated. Use the variant that includes the <var>TMaskOptions</var> argument.
+          </remark>
+          <p>
+            MatchesMaskList creates a <var>TMaskList</var> instance which uses the values in the Mask, Separator and Options parameters. Its <var>Matches</var> method is called to compare the value in Filename to the mask values in the list.
+          </p>
+          <p>
+            The return value is <b>True</b> when Filename matches at least one of the masks in the list.
+          </p>
+        </descr>
+        <seealso>
+          <link id="MatchesWindowsMaskList"/>
+          <link id="TMaskOption"/>
+          <link id="TMaskList"/>
+          <link id="MasksOverview"/>
+        </seealso>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="MatchesMaskList.Result"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesMaskList.FileName"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesMaskList.Mask"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesMaskList.Separator"><short/></element>
-      <!-- function Visibility: default -->
+      <element name="MatchesMaskList.Result">
+        <short>True when Filename matches at least one of the masks in the list</short>
+      </element>
+      <element name="MatchesMaskList.FileName">
+        <short>File name compared to the file masks in Mask</short>
+      </element>
+      <element name="MatchesMaskList.Mask">
+        <short>one or more file mask expressions separated by one of the values in Separator</short>
+      </element>
+      <element name="MatchesMaskList.Separator">
+        <short>Character(s) used as a separator between mask expressions in Mask</short>
+      </element>
+      <element name="MatchesMaskList.CaseSensitive">
+        <short>True if the file name to mask comparison is case sensitive</short>
+      </element>
+      <element name="MatchesMaskList.Options">
+        <short>TMaskOption values which enable or disable features in the comparison</short>
+      </element>
+
       <element name="MatchesWindowsMaskList">
-        <short>Test if the file name matches at least one of passed masks separated by the parameter Separator. Implements some special rules for a Windows© filesystem comparison.</short>
-        <descr/>
-        <errors/>
-        <seealso/>
+        <short>
+          Determine whether the specified file name matches at least one of the specified masks
+        </short>
+        <descr>
+          <p>
+            <var>MatchesWindowsMaskList</var> is an overloaded <var>Boolean</var> function used to determine whether the specified file name matches at least one of the specified masks. MatchesWindowsMaskList is similar to <var>MatchesMaskList</var>, but provides support for Windows-style file system masks in the Mask argument. This includes use of the following:
+          </p>
+          <dl>
+            <dt>foo*.*</dt>
+            <dd>
+              Matches all files starting with 'foo' regardless of the file extension. Same as  foo* using MatchesMaskList.
+            </dd>
+            <dt>foo*.</dt>
+            <dd>Matches foo* but must not include a file extension.</dd>
+            <dt>*.</dt>
+            <dd>Matches any file name, but must not include a file extension.</dd>
+            <dt>foo.</dt>
+            <dd>Matches foo but not foo.txt.</dd>
+            <dt>foo.*</dt>
+            <dd>Matches foo, foo.txt, or foo.bar.</dd>
+            <dt>*.*</dt>
+            <dd>Matches any file name with an extension.</dd>
+          </dl>
+          <p>
+            Overloaded variants of the routine provide arguments and configuration settings, including:
+          </p>
+          <dl>
+            <dt>Filename</dt>
+            <dd>File name compared to the file masks in Mask.</dd>
+            <dt>Mask</dt>
+            <dd>Contains one or more file mask expressions separated by one of the values in Separator.</dd>
+            <dt>Separator</dt>
+            <dd>Contains the character(s) used as a separator between mask expressions in Mask. The default separator is the SemiColon (;) character.</dd>
+            <dt>Options</dt>
+            <dd>Contains TMaskOption values which enable or disable features in the comparison. The default value is an empty set ([]).</dd>
+            <dt>CaseSensitive</dt>
+            <dd>Indicates whether the file name to mask comparison is case sensitive.</dd>
+          </dl>
+          <remark>
+            Please note: The overloaded variant which includes the <var>CaseSensitive</var> argument has been deprecated. Use the variant that includes the <var>TMaskOptions</var> argument.
+          </remark>
+          <p>
+            MatchesWindowsMaskList creates a <var>TMaskList</var> instance which uses the values in the Mask, Separator and Options parameters. Its <var>MatchesWindowsMask</var> method is called to compare the value in Filename to the Windows-style masks in the list.
+          </p>
+          <p>
+            The return value is <b>True</b> when Filename matches at least one of the masks in the list.
+          </p>
+        </descr>
+        <seealso>
+          <link id="MatchesMaskList"/>
+          <link id="TMaskOption"/>
+          <link id="TMaskList"/>
+          <link id="MasksOverview"/>
+        </seealso>
       </element>
-      <!-- function result Visibility: default -->
-      <element name="MatchesWindowsMaskList.Result"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesWindowsMaskList.FileName"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesWindowsMaskList.Mask"><short/></element>
-      <!-- argument Visibility: default -->
-      <element name="MatchesWindowsMaskList.Separator"><short/></element>
+      <element name="MatchesWindowsMaskList.Result">
+        <short><b>True</b> when Filename matches at least one of the masks in the list</short>
+      </element>
+      <element name="MatchesWindowsMaskList.FileName">
+        <short>File name compared to the file masks in Mask</short>
+      </element>
+      <element name="MatchesWindowsMaskList.Mask">
+        <short>one or more file mask expressions separated by one of the values in Separator</short>
+      </element>
+      <element name="MatchesWindowsMaskList.Separator">
+        <short>Character(s) used as a separator between mask expressions in Mask</short>
+      </element>
+      <element name="MatchesWindowsMaskList.CaseSensitive">
+        <short>True if the file name to mask comparison is case sensitive</short>
+      </element>
+      <element name="MatchesWindowsMaskList.Options">
+        <short>TMaskOption values which enable or disable features in the comparison</short>
+      </element>
+
+      <topic name="MasksOverview">
+        <short>Masks Overview</short>
+        <descr>
+          <p>
+            <b>What is a Mask</b>
+          </p>
+          <p>
+            A mask is an expression composed of literal characters, character sets, and wildcards. A mask  is used in TMask and related routines to determine if a string containing a specific value matches the mask expression.
+          </p>
+
+          <p>
+            <b>Literal Characters</b>
+          </p>
+          <p>
+            Each literal character corresponds to a single character in a compared value.
+          </p>
+
+          <p>
+            <b>Character Sets</b>
+          </p>
+          <p>
+            A character set begins with an opening Square Bracket character (<b>[</b>) and ends with a closing Square Bracket character (<b>]</b>). Values between the brackets represent literal characters or a range of characters which are included in (or excluded from) the character set.
+          </p>
+          <p>
+            A range is defined using a starting character, a dash (<b>-</b>), and an ending character. The character set matches a single character in a compared value. When an Exclamation Point character (<b>!</b>) is found after the first bracket, the values in the character set are excluded from matches using the mask.
+          </p>
+          <p>
+            For example, an alpha-numeric character set could be represented using the following:
+          </p>
+          <code>[a-zA-Z0-9]</code>
+          <p>
+            And, a character set which excludes numeric values could be represented using the following:
+          </p>
+          <code>[!0-9]</code>
+
+          <p>
+            <b>Wildcard Characters</b>
+          </p>
+          <p>
+            Wildcard characters allow one or more literal characters to be considered as a match in the mask value, and includes the <b>?</b> and <b>*</b> characters. <b>?</b> matches a single character (regardless of its value). <b>*</b> matches any number of characters (regrardless of their values).
+          </p>
+
+          <p>
+            <b>Mask Examples</b>
+          </p>
+          <!-- TODO: Add more mask examples -->
+          <dl>
+            <dt>abc.ext</dt>
+            <dd>Matches a single file named "abc.ext".</dd>
+            <dt>a[blt]c.ext</dt>
+            <dd>Matches "abc.ext", "alc.ext", or "atc.ext".</dd>
+            <dt>a[b-d]c.ext</dt>
+            <dd>Matches "abc.ext", "acc.ext", or "adc.ext".</dd>
+            <dt>foo*</dt>
+            <dd>Matches any file that starts with "foo", including those with a file extension.</dd>
+            <dt>*</dt>
+            <dd>Matches any file, including those with a file extension.</dd>
+            <dt>*.</dt>
+            <dd>Matches any file that does not have an extension.</dd>
+            <dt>ab??ef.txt</dt>
+            <dd>Matches abcdef.txt and abrtef.txt.</dd>
+          </dl>
+
+          <p>
+            <b>Using Masks</b>
+          </p>
+          <p>
+            Mask values are normally passed as an argument to new instances of TMask, or passed as an argument to routines like MatchesMask, MatchesMaskList, et. al. In general, the mask is used to find file names that match the mask expression. But they are not limited that single use case. They can be used to determine if any string value matches a valid mask expression. Sort of like regular expressions without all of the complexity (and most of the functionality).
+          </p>
+
+          <remark>
+            Please note: Mask values as used in TMask are not related to the mask values used in the TMaskEdit control. Although both compare string values to determine if they match a particular pattern, they use different symbols and syntax.
+          </remark>
+        </descr>
+      </topic>
+
     </module>
     <!-- Masks -->
   </package>
docs-lazutils.diff (84,911 bytes)   

Juha Manninen

2020-10-29 16:46

developer   ~0126636

Applied, thanks.

Issue History

Date Modified Username Field Change
2020-10-28 03:30 Don Siders New Issue
2020-10-28 03:30 Don Siders File Added: docs-lcl.diff
2020-10-28 03:30 Don Siders File Added: docs-lazutils.diff
2020-10-29 16:17 Juha Manninen Assigned To => Juha Manninen
2020-10-29 16:17 Juha Manninen Status new => assigned
2020-10-29 16:46 Juha Manninen Status assigned => resolved
2020-10-29 16:46 Juha Manninen Resolution open => fixed
2020-10-29 16:46 Juha Manninen Fixed in Revision => 64082
2020-10-29 16:46 Juha Manninen LazTarget => -
2020-10-29 16:46 Juha Manninen Note Added: 0126636
2020-10-29 16:51 Juha Manninen Description Updated View Revisions
2020-10-29 16:51 Juha Manninen Fixed in Revision 64082 => r64082
2020-10-29 18:10 Don Siders Status resolved => closed