View Issue Details

IDProjectCategoryView StatusLast Update
0038532LazarusDocumentationpublic2021-02-24 10:30
ReporterDon Siders Assigned ToJuha Manninen  
PrioritynormalSeverityminorReproducibilityN/A
Status closedResolutionfixed 
Product Version2.1 (SVN) 
Summary0038532: Documentation updates for LCL, LazUtils
DescriptionLazUtils modified files:

* docs/xml/lazutils/lazfileutils.xml
* docs/xml/lazutils/lazstringutils.xml

See attached: docs-lazutils.diff

LCL modified files:

* docs/xml/lcl/imglist.xml
* docs/xml/lcl/interfacebase.xml
* docs/xml/lcl/valedit.xml

See attached: docs-lcl.diff
TagsNo tags attached.
Fixed in Revisionr64658
LazTarget-
Widgetset
Attached Files

Activities

Don Siders

2021-02-22 16:09

reporter  

docs-lazutils.diff (53,680 bytes)   
Index: docs/xml/lazutils/lazfileutils.xml
===================================================================
--- docs/xml/lazutils/lazfileutils.xml	(revision 64651)
+++ docs/xml/lazutils/lazfileutils.xml	(working copy)
@@ -19,7 +19,6 @@
         </remark>
       </descr>
 
-    <!-- function Visibility: default -->
       <element name="CompareFilenames">
         <short>
           Gets the relative sort order for the specified file names
@@ -45,22 +44,18 @@
         </seealso>
       </element>
 
-      <!-- function result Visibility: default -->
       <element name="CompareFilenames.Result">
         <short>Relative sort order for the specified file names</short>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="CompareFilenames.Filename1">
         <short>First file name for the comparison</short>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="CompareFilenames.Filename2">
         <short>Second file name for the comparison</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CompareFilenamesIgnoreCase">
         <short>
           Gets the relative sort order for case-insensitive file names
@@ -86,23 +81,16 @@
           <link id="CompareFilenames"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CompareFilenamesIgnoreCase.Result">
         <short>Relative sort order for the file names</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CompareFilenamesIgnoreCase.Filename1">
         <short>First file name for the comparison</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CompareFilenamesIgnoreCase.Filename2">
         <short>Second file name for the comparison</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CompareFileExt">
         <short>
           Performs a sort order comparison for the specified file name and extension
@@ -221,11 +209,25 @@
             Ext can contain the '<b>.</b>' (<b>Period</b>) character used in the extension, but it is not required.
           </p>
           <p>
-            <var>CaseSensitive</var> indicates if case-sensitivity is used when comparing parameter values. When set to <b>True</b>, the comparision is limited to values in the ASCII character set. <var>StrLComp</var> or <var>StrLIComp</var> is called to compare the values in Filename to the values in Ext.
+            <var>CaseSensitive</var> indicates if case-sensitivity is used when comparing parameter values. When set to <b>True</b>, the comparison is limited to values in the ASCII character set. <var>StrLComp</var> or <var>StrLIComp</var> is called to compare the values in Filename to the values in Ext.
           </p>
           <p>
-            The return value is <b>True</b> when Filename uses the file extension in Ext. The return value is <b>False</b> when Filename is an empty string (<b>''</b>), does not include a '<b>.</b>' character that marks the start of the file extension, or does not use the file extension in Ext.
+            The return value is <b>True</b> when Filename uses the file extension in Ext. The return value is <b>False</b> for the following conditions:
           </p>
+          <ul>
+            <li>
+              Filename is an empty string (<b>''</b>).
+            </li>
+            <li>
+              Filename does not have a '<b>.</b>' character that marks the start of the file extension.
+            </li>
+            <li>
+              The extension in Filename has a different length than Ext.
+            </li>
+            <li>
+              Filename has a different file extension than Ext.
+            </li>
+          </ul>
         </descr>
         <seealso>
           <link id="FilenameExtIn"/>
@@ -245,7 +247,7 @@
       </element>
 
       <element name="FilenameExtIn">
-        <short>Determies if the file name uses one of the specified file extensions</short>
+        <short>Determines if the file name uses one of the specified file extensions</short>
         <descr>
           <p>
             <var>FilenameExtIn</var> is a <var>Boolean</var> function used to determine if the file name in the <var>Filename</var> parameter uses one of the file extension in <var>Exts</var>.
@@ -361,9 +363,7 @@
           <p>
             On Windows, the FilenameIsWinAbsolute function is called in the implementation. FilenameIsWinAbsolute takes Device identifiers into consideration when examining the value in TheFilename. For example:
           </p>
-          <code>
-            D:\db\employee.fdb
-          </code>
+          <code>D:\db\employee.fdb</code>
           <p>
             The return value is False if TheFilename (without the optional device identifier) is an empty string (''), or does not start with the directory separator for the environment.
           </p>
@@ -370,18 +370,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FilenameIsAbsolute.Result">
         <short>True when the file name is not a relative path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsAbsolute.TheFilename">
         <short>Path and file name to use in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FilenameIsWinAbsolute">
         <short>
           Determines if the specified value is an absolute file path (not a relative one)
@@ -393,9 +388,7 @@
           <p>
             On Windows, the FilenameIsWinAbsolute function is called in the implementation of FilenameIsAbsolute. FilenameIsWinAbsolute takes Device identifiers into consideration when examine the value in TheFilename. For example:
           </p>
-          <code>
-            D:\db\employee.fdb
-          </code>
+          <code>D:\db\employee.fdb</code>
           <p>
             The return value is False if TheFilename (without the optional device identifier)is an empty string (''), or does not start with the directory separator for the environment.
           </p>
@@ -402,18 +395,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FilenameIsWinAbsolute.Result">
         <short>True when the file name is not a relative path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsWinAbsolute.TheFilename">
         <short>Path and file name to use in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FilenameIsUnixAbsolute">
         <short>
           Determines if the specified value is an absolute file path (not a relative one)
@@ -428,13 +416,9 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FilenameIsUnixAbsolute.Result">
         <short>True when the file name is not a relative path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsUnixAbsolute.TheFilename">
         <short>Path and file name to use in the function</short>
       </element>
@@ -445,7 +429,7 @@
         </short>
         <descr>
           <p>
-            <var>ForceDirectory</var>  is a Boolean function which creates the specified directory if it does not already exist. ForceDirectory ensures that a trailing path delimiter exists in <var>DirectoryName</var> prior to checking the file system. Duplicate adjacent path delimiters (like '//foo//bar/foobar/' or '\\foo\\bar\foobar\') are removed prior to checking the directory path.
+            <var>ForceDirectory</var> is a Boolean function which creates the specified directory if it does not already exist. ForceDirectory ensures that a trailing path delimiter exists in <var>DirectoryName</var> prior to checking the file system. Duplicate adjacent path delimiters (like '//foo//bar/foobar/' or '\\foo\\bar\foobar\') are removed prior to checking the directory path.
           </p>
           <p>
             Each directory in the specified path is validated by calling <var>DirPathExists</var>. ForceDirectory calls <var>CreateDirUTF8</var> if a directory does not exist, and may exit with a return value of <b>False</b> if directory creation is not successful.
@@ -467,7 +451,6 @@
         <short>Path information for the operation</short>
       </element>
 
-      <!-- procedure Visibility: default -->
       <element name="CheckIfFileIsExecutable">
         <short>
           Examines the specified file to see if it is executable
@@ -523,13 +506,10 @@
           </dl>
         </errors>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CheckIfFileIsExecutable.AFilename">
         <short>File name to examine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsExecutable">
         <short>
           Determines if the specified file name is executable
@@ -541,13 +521,9 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsExecutable.Result">
         <short>True if the file is executable on the platform or OS</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsExecutable.AFilename">
         <short>File name to examine</short>
       </element>
@@ -601,7 +577,6 @@
         <short>File name examined in the routine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsReadable">
         <short>
           Indicates if the specified file name is readable
@@ -616,18 +591,13 @@
           <link id="#rtl.baseunix.FpAccess">FpAccess</link>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsReadable.Result">
         <short>True when the specified file name is readable</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsReadable.AFilename">
         <short>File name to examine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsWritable">
         <short>
           Indicates if the specified file name is writable
@@ -634,23 +604,18 @@
         </short>
         <descr>
           <p>
-            FileIsWritable is a Boolean function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file.
+            <var>FileIsWritable</var> is a <var>Boolean</var> function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file.
           </p>
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsWritable.Result">
         <short>True when the specified file name is writable</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsWritable.AFilename">
         <short>File name to examine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsText">
         <short>
           Determines if the specified file contains plain text content
@@ -657,7 +622,7 @@
       </short>
         <descr>
           <p>
-            FileIsText is a Boolean function used to determine if the specified file contains plain text content. The overloaded variant that includes the FileReadable argument is used to examine the content in the file.
+            <var>FileIsText</var> is a <var>Boolean</var> function used to determine if the specified file contains plain text content. The overloaded variant that includes the FileReadable argument is used to examine the content in the file.
           </p>
           <p>
             FileIsText calls FileOpenUtf8 for the specified file name. The return value is False is the file handle contains feInvalidHandle.
@@ -676,28 +641,21 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsText.Result">
         <short>True when the file contains plain text content</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsText.AFilename">
         <short>File name to examine in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsText.FileReadable">
         <short>Indicates if the specified file was successfully opened and read</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FilenameIsTrimmed">
         <short/>
         <descr>
           <p>
-            FilenameIsTrimmed is an overloaded Boolean function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The  return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters.
+            <var>FilenameIsTrimmed</var> is an overloaded <var>Boolean</var> function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The  return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters.
           </p>
           <p>
             Use TrimFilename to remove leading or trailing whitespace, duplicate directory separators, or relative path symbols.
@@ -705,34 +663,25 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FilenameIsTrimmed.Result">
         <short>False when the file name needs to trimmed</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsTrimmed.TheFilename">
         <short>File name to examine in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsTrimmed.StartPos">
         <short>PChar with the file name value</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsTrimmed.NameLen">
         <short>Length of the file name</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="TrimFilename">
         <short>
           Removes leading and trailing spaces, and resolves special characters
         </short>
         <descr>
-          <var>TrimFilename</var> is a String function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//').
+          <var>TrimFilename</var> is a <var>String</var> function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//').
         </descr>
         <errors/>
         <seealso>
@@ -744,13 +693,9 @@
           <link id="TrimAndExpandDirectory"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="TrimFilename.Result">
         <short>New value  for the path and file name</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimFilename.AFilename">
         <short>Path and file name for the operation</short>
       </element>
@@ -772,7 +717,6 @@
         <short>File name examined in the routine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CleanAndExpandFilename">
         <short>
           Removes whitespace and resolves special characters in the specified file name
@@ -779,23 +723,18 @@
         </short>
         <descr>
           <p>
-            CleanAndExpandFilename is a String function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string ('').
+            <var>CleanAndExpandFilename</var> is a <var>String</var> function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string ('').
           </p>
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CleanAndExpandFilename.Result">
         <short>File name with whitespace removed and special characters resolved</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CleanAndExpandFilename.Filename">
         <short>File name to examine in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CleanAndExpandDirectory">
         <short>
           Removes whitespace and resolves special characters in the specified path
@@ -810,20 +749,15 @@
           <link id="AppendPathDelim"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CleanAndExpandDirectory.Result">
         <short>
           Path information after removing whitespace and resolving special characters
         </short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CleanAndExpandDirectory.Filename">
         <short>Path information for the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="TrimAndExpandFilename">
         <short>
           Cleans and resolves a file path to the specified base directory name
@@ -838,23 +772,16 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="TrimAndExpandFilename.Result">
         <short>Cleaned and resolved file path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimAndExpandFilename.Filename">
         <short>File name for the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimAndExpandFilename.BaseDir">
         <short>Base directory name used for a relative file path</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="TrimAndExpandDirectory">
         <short>
           Cleans and resolves a relative path to a base directory
@@ -872,23 +799,16 @@
           <link id="TrimFilename"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="TrimAndExpandDirectory.Result">
         <short>Path information cleaned and resolved to the specified base directory</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimAndExpandDirectory.Filename">
         <short>Path information for the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimAndExpandDirectory.BaseDir">
         <short>Base directory used to resolve a relative path</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CreateRelativePath">
         <short>
           Creates a relative path from BaseDirectory to Filename
@@ -906,23 +826,15 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CreateRelativePath.Result">
         <short>Relative path from the base directory for the file name</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CreateRelativePath.Filename">
         <short>File name for the operation</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CreateRelativePath.BaseDirectory">
         <short>Base directory for the relative path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CreateRelativePath.UsePointDirectory">
         <short>
           True if '.' (current directory symbol) is prepended to the relative path
@@ -929,7 +841,6 @@
         </short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsInPath">
         <short>
           Returns True if Filename exists in the specified Path
@@ -953,18 +864,12 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsInPath.Result">
         <short>True when the file exists in the specified path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsInPath.Filename">
         <short>File name to locate</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsInPath.Path">
         <short>Path used for the operation</short>
       </element>
@@ -1012,7 +917,7 @@
         <seealso/>
       </element>
       <element name="ShortDisplayFilename.Result">
-        <short>Shortened version of the specifed file name</short>
+        <short>Shortened version of the specified file name</short>
       </element>
       <element name="ShortDisplayFilename.aFileName">
         <short>File name examined in the routine</short>
@@ -1091,7 +996,6 @@
         <short>File name examined in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="AppendPathDelim">
         <short>
           Adds a trailing path delimiter when needed
@@ -1103,18 +1007,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="AppendPathDelim.Result">
         <short>Path value with a trailing path delimiter</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="AppendPathDelim.Path">
         <short>Path value to examine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="ChompPathDelim">
         <short>
           Removes a trailing path delimiter from the specified value
@@ -1126,13 +1025,9 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="ChompPathDelim.Result">
         <short>Path information after removing the trailing path delimiter</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="ChompPathDelim.Path">
         <short>Path information for the function</short>
       </element>
@@ -1392,7 +1287,6 @@
         <short>Length in characters for the search paths list</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileExistsUTF8">
         <short>
           Indicates if the specified file name exists
@@ -1405,17 +1299,14 @@
         <seealso/>
       </element>
 
-      <!-- function result Visibility: default -->
       <element name="FileExistsUTF8.Result">
         <short>True when the specified file name exists</short>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="FileExistsUTF8.Filename">
         <short>UTF-8-encoded file name to locate in the local file system</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileAgeUTF8">
         <short>
           Returns the last modification time for the file in FileDate format
@@ -1433,18 +1324,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileAgeUTF8.Result">
         <short>Last modification time for the file in FileDate format</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileAgeUTF8.FileName">
         <short>File name examined in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="DirectoryExistsUTF8">
         <short>
           Determine if the specified path exists on the local file system
@@ -1456,18 +1342,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="DirectoryExistsUTF8.Result">
         <short>True when the directory exists in the file system</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="DirectoryExistsUTF8.Directory">
         <short>Directory name to locate in the file system</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="ExpandFileNameUTF8">
         <short>
           Expands the values in FileName and BaseDir to an absolute file name
@@ -1486,23 +1367,16 @@
           <link id="ResolveDots"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="ExpandFileNameUTF8.Result">
         <short>The file name with an absolute path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="ExpandFileNameUTF8.FileName">
         <short>File name examined in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="ExpandFileNameUTF8.BaseDir">
         <short>Base directory used to resolve a relative path</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FindFirstUTF8">
         <short>
           Starts searching for files matching the specified path value
@@ -1523,28 +1397,19 @@
           <link id="#rtl.sysutils.FindFirst">FindFirst</link>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FindFirstUTF8.Result">
         <short>Last error number encountered in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FindFirstUTF8.Path">
         <short>Path and/or file name to locate</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FindFirstUTF8.Attr">
         <short>File attributes to include in the search</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FindFirstUTF8.Rslt">
         <short>Search record for the first matching file</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FindNextUTF8">
         <short>
           Locates another file matching the search criteria
@@ -1562,18 +1427,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FindNextUTF8.Result">
         <short>Last error number</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FindNextUTF8.Rslt">
         <short>Search criteria for the function</short>
       </element>
 
-      <!-- procedure Visibility: default -->
       <element name="FindCloseUTF8">
         <short>
           Frees resources allocated to the specified search record
@@ -1586,12 +1446,10 @@
         <seealso/>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="FindCloseUTF8.F">
         <short>Search record to free in the procedure</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileSetDateUTF8">
         <short>
           Sets the last modification time for the file
@@ -1609,23 +1467,16 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileSetDateUTF8.Result">
         <short>Last error number in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSetDateUTF8.FileName">
         <short>File name to update in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSetDateUTF8.Age">
         <short>New value for the last modification time</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileGetAttrUTF8">
           <short>
             Gets the value of file attributes for the specified file name
@@ -1666,18 +1517,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileGetAttrUTF8.Result">
         <short>File attribute value for the specified file name</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileGetAttrUTF8.FileName">
         <short>File name for the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileSetAttrUTF8">
         <short>
           Sets the file attribute value for the specified file name
@@ -1721,23 +1567,16 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileSetAttrUTF8.Result">
         <short>Last error number from the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSetAttrUTF8.Filename">
         <short>File name to update in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSetAttrUTF8.Attr">
         <short>File attribute value for the specified file name</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="DeleteFileUTF8">
         <short>
           Deletes the specified file name
@@ -1755,18 +1594,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="DeleteFileUTF8.Result">
         <short>True if the specified file name is deleted</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="DeleteFileUTF8.FileName">
         <short>File name to delete in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="RenameFileUTF8">
         <short>
           Renames a file to the specified value
@@ -1785,23 +1619,16 @@
         <errors/>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="RenameFileUTF8.Result">
         <short>True if the file is successfully renamed to the new value</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="RenameFileUTF8.OldName">
         <short>Existing name for the file</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="RenameFileUTF8.NewName">
         <short>New name for the file</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileSearchUTF8">
         <short>
           Searches for a file with the specified name in the list of directory paths
@@ -1822,23 +1649,16 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileSearchUTF8.Result">
         <short>Path and file name for the matching file, or an empty string</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSearchUTF8.Name">
         <short>File name to locate in the list of directory paths</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSearchUTF8.DirList">
         <short>The delimited list of directory paths to search</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsReadOnlyUTF8">
         <short>
           Determines if the specified file is marked as read-only
@@ -1850,18 +1670,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsReadOnlyUTF8.Result">
         <short>True when the file is marked as read-only</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsReadOnlyUTF8.FileName">
         <short>File name to examine in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="GetCurrentDirUTF8">
         <short>
           Gets the name for the current directory
@@ -1881,13 +1696,10 @@
           <link id="#rtl.sysutils.GetCurrentDir">GetCurrentDir</link>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="GetCurrentDirUTF8.Result">
         <short>Name for the current directory</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="SetCurrentDirUTF8">
         <short>
           Sets the current directory to the specified name
@@ -1916,18 +1728,13 @@
         </errors>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="SetCurrentDirUTF8.Result">
         <short>True if the current directory was successfully changed to the new value</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="SetCurrentDirUTF8.NewDir">
         <short>Directory name to use as the current directory</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CreateDirUTF8">
         <short>
           Creates a new directory with the specified name
@@ -1947,18 +1754,13 @@
         </errors>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CreateDirUTF8.Result">
         <short>True if the new directory is successfully created</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CreateDirUTF8.NewDir">
         <short>Name for the new directory</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="RemoveDirUTF8">
         <short>
           Removes the directory with the specified name
@@ -1981,18 +1783,13 @@
           <link id="#rtl.sysutils.RemoveDir">RemoveDir</link>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="RemoveDirUTF8.Result">
         <short>True when the directory is successfully removed</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="RemoveDirUTF8.Dir">
         <short>Name of the directory to remove in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="ForceDirectoriesUTF8">
         <short>
           Creates the specified directories if they do not already exist
@@ -1999,7 +1796,7 @@
         </short>
         <descr>
           <p>
-            <var>ForceDirectories</var>  is a <var>Boolean</var> function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function.
+            <var>ForceDirectories</var> is a <var>Boolean</var> function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function.
           </p>
           <p>
             ForceDirectories raises an <var>EInOutError</var> exception with the message in <var>SCannotCreateEmptyDir</var> when Dir contains an empty string ('').
@@ -2020,15 +1817,11 @@
           <link id="ForceDirectory"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="ForceDirectoriesUTF8.Result">
         <short>
           True when directories exist or are successfully created in the function
         </short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="ForceDirectoriesUTF8.Dir">
         <short>Path information to examine the function</short>
       </element>
@@ -2110,9 +1903,7 @@
           <p>
             For UNIX-like environments, the return value can contain information that indicates the permissions for the user, group, and owner of the file as returned from the FPStat routine. It also includes the file user and group IDs, file size, and modification timestamp. For example:
           </p>
-          <code>
-ld-rwxrwxrwx Owner: UID.GID Size: 99999 Modified: MM/DD/YYYY hh:nn
-          </code>
+          <code>ld-rwxrwxrwx Owner: UID.GID Size: 99999 Modified: MM/DD/YYYY hh:nn</code>
           <dl>
             <dt>l</dt>
              <dd>File is a symbolic link</dd>
@@ -2150,9 +1941,7 @@
           <p>
             For the Amiga platform, the content in the return value is derived using a  TFileInfoBlock for a shared lock on the file. The return value can be an empty string if the file could not be locked using a shared lock on the file system. It can contain values like the following:
           </p>
-        <code>
- asperwd
-        </code>
+        <code>asperwd</code>
         <dl>
           <dt>a</dt>
           <dd>File is an archived (unchanged) file</dd>
@@ -2172,9 +1961,7 @@
         <p>
           For Windows platforms, the return value contains only the modification date/time for the file using the format:
         </p>
-        <code>
-Modified: MM/DD/YYYY hh:mm
-        </code>
+        <code>Modified: MM/DD/YYYY hh:mm</code>
         <p>
           The return value can be 'Modified: ?' if an exception is encountered when getting the date/time value for the file.
         </p>
@@ -2414,7 +2201,7 @@
             If the directory does not exist and Create contains True, the <var>ForceDirectoriesUTF8</var> routine is called to create any missing directories for the path. An <var>EInOutError</var> exception is raised if any missing directory in the path cannot be created.
           </p>
           <p>
-            GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help viewer  (LHelp).
+            GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help viewer (LHelp).
           </p>
         </descr>
         <seealso>
@@ -2504,9 +2291,7 @@
           <p>
             GetTempFileNameUTF8 signals the OnGetTempFile event handler (when assigned) to get the value used as the temporary file name. When OnGetTempFile has not been assigned, a string is constructed using the path information in Dir and a numeric suffix to make the file name unique. For example:
           </p>
-          <code>
-/usr/tmp/TMP0.tmp
-          </code>
+          <code>/usr/tmp/TMP0.tmp</code>
           <p>
             GetTempFileNameUTF8 examines the files in the specified directory to determine if a file already exists which starts with the value in  Prefix. If a file is located in the directory, a numeric suffix (starting at 0) is appended to the base file name in Prefix to build a temporary file name which does not already exist in the directory.
           </p>
@@ -2532,11 +2317,11 @@
           <p>
             The implementation of IsUNCPath is platform- and/or OS-specific. For the Windows platform, IsUNCPath checks Path to see if it begins with the double backslash notation used for a UNC path. For example:
           </p>
-          <code>
-  \\C:\directory\
-  \\?\C:\directory\
-  \\?\UNC\volume\directory\
-          </code>
+<code>
+\\C:\directory\
+\\?\C:\directory\
+\\?\UNC\volume\directory\
+</code>
           <p>
             For UNIX-like environments, as well as the Amiga platform, the return value is always False. UNC paths are not used on those platforms.
           </p>
@@ -2562,17 +2347,17 @@
           <p>
             The return value contains information needed to access shared resources by their host and volume names, and contains one of the following formats:
           </p>
-          <code>
-  \\server-name\shared-resource-path-name\
-  \\mypc\nas-drive\
-  \\?\c:\
-  \\?\UNC\c:\
-          </code>
+<code>
+\\server-name\shared-resource-path-name\
+\\mypc\nas-drive\
+\\?\c:\
+\\?\UNC\c:\
+</code>
           <p>
             ExtractUNCVolume calls the <var>IsUNCPath</var> function to determine if the value in <var>Path</var> starts with the UNC naming delimiters. The return value is an empty string (<b>''</b>), and no additional actions are performed in the function, when Path does not use UNC notation.
           </p>
           <p>
-            ExtractUNCVolume examines the characters in Path to determine if it uses the long or the short format for UNC notation. Long format notation begins with the characters <b>'\\?\'</b>  or <b>'\\?\UNC\'</b> followed by a drive designation and optional path information such as 'c:\'. Short format notation uses a host name and a shared resource identifier such as <b>'\\mypc\nas-drive\'</b>.
+            ExtractUNCVolume examines the characters in Path to determine if it uses the long or the short format for UNC notation. Long format notation begins with the characters <b>'\\?\'</b> or <b>'\\?\UNC\'</b> followed by a drive designation and optional path information such as 'c:\'. Short format notation uses a host name and a shared resource identifier such as <b>'\\mypc\nas-drive\'</b>.
           </p>
         </descr>
         <seealso>
@@ -2595,10 +2380,10 @@
           <p>
             When FileName uses Universal Naming Convention (UNC),  the return value will contain any server and share/volume information included in the parameter. For example:
           </p>
-          <code>
-  \\server-name\share-name\
-  \\?\C:\
-         </code>
+<code>
+\\server-name\share-name\
+\\?\C:\
+</code>
          <p>
            For UNIX-like environments (as well as WinCE), an initial path delimiter marks the root directory in the file system.
          </p>
@@ -2608,9 +2393,7 @@
          <p>
            For the Windows platform, a drive designation up to and including the first path delimiter are used as the root directory. For example:
          </p>
-         <code>
-C:\
-          </code>
+         <code>C:\</code>
         </descr>
         <seealso/>
       </element>
@@ -2739,7 +2522,6 @@
         <short>Command line option examined in the function</short>
       </element>
 
-      <!-- procedure type Visibility: default -->
       <element name="TInvalidateFileStateCacheEvent">
         <short>
           Specifies the event signalled for an invalid file state in the file cache
@@ -2755,12 +2537,10 @@
         </seealso>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="TInvalidateFileStateCacheEvent.Filename">
         <short>File name for the event notification</short>
       </element>
 
-      <!-- variable Visibility: default -->
       <element name="OnInvalidateFileStateCache">
         <short>
           Implements the event handler for a file with an invalid file state
@@ -2778,7 +2558,6 @@
         </seealso>
       </element>
 
-      <!-- procedure Visibility: default -->
       <element name="InvalidateFileStateCache">
         <short>
           Signals the OnInvalidateFileStateCache event handler
Index: docs/xml/lazutils/lazstringutils.xml
===================================================================
--- docs/xml/lazutils/lazstringutils.xml	(revision 64651)
+++ docs/xml/lazutils/lazstringutils.xml	(working copy)
@@ -81,10 +81,10 @@
       </element>
 
       <element name="PosI">
-        <short>A case-insensitive version of the Pos routine</short>
+        <short>A case-insensitive optimized version of the Pos routine</short>
         <descr>
           <p>
-            <var>PosI</var> implements a case-insensitive version of the <var>Pos</var> routine found the RTL <file>system</file> unit. It only accepts <var>String</var> values in its parameters, unlike the RTL overloaded variants which accept combinations of the Char, ShortString, AnsiString, UnicodeString, WideString, and Variant types.
+            <var>PosI</var> implements a case-insensitive optimized version of the <var>Pos</var> routine found the RTL <file>system</file> unit. It only accepts <var>String</var> values in its parameters, unlike the RTL overloaded variants which accept combinations of the Char, ShortString, AnsiString, UnicodeString, WideString, and Variant types.
           </p>
           <p>
             It is also an alternative to the <var>ContainsText</var> routine in the RTL <file>StrUtils</file> unit, which has a <b>very</b> slow implementation.
@@ -105,7 +105,7 @@
         </seealso>
       </element>
       <element name="PosI.Result">
-        <short>Positionof the sub-string witin the searched value, or 0 when not found</short>
+        <short>Position of the sub-string within the searched value, or 0 when not found</short>
       </element>
       <element name="PosI.SubStr">
         <short>Value to locate in the searched value</short>
@@ -236,7 +236,9 @@
       </element>
 
       <element name="LineBreaksToDelimiter">
-        <short>Converts CR or LF characters in a string to the specified delimiter character</short>
+        <short>
+          Converts CR or LF characters in a string to the specified delimiter character
+        </short>
         <descr/>
         <seealso/>
       </element>
@@ -251,11 +253,13 @@
       </element>
 
       <element name="ConvertLineEndings">
-        <short/>
+        <short>Deprecated</short>
         <descr>
           <remark>Deprecated. Use LineBreaksToSystemLineBreaks instead.</remark>
         </descr>
-        <seealso/>
+        <seealso>
+          <link id="LineBreaksToSystemLineBreaks"/>
+        </seealso>
       </element>
       <element name="ConvertLineEndings.Result">
         <short/>
@@ -437,7 +441,9 @@
           <p>
             <var>BeautifyLineXY</var> is a <var>String</var> function used to combine the values in the <var>Filename</var>, <var>Line</var>, <var>X</var> and <var>Y</var> arguments into a formatted message. The message is in the form:
           </p>
-<code>LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s).</code>
+<code>
+  LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s).
+</code>
           <p>
             <var>Filename</var> contains a file name used at the start of the formatted message.
           </p>
@@ -634,19 +640,25 @@
       </element>
 
       <element name="StringToStringList">
-        <short>Stores the specified string as lines in a TStrings instance</short>
+        <short>Stores a multi-line string as seperate lines in a TStrings instance</short>
         <descr>
           <p>
-            <b>LF</b> (<b>#10</b>) characters found in <var>s</var> control when a line of text is added in the <var>TStrings</var> instance. The end-of-line character is not stored in the TStrings instance. If no end-of-line characters are found in S, then a single line of text is added to the string list.
+            <var>StringToStringList</var> is a procedure used to convert the multi-line String in <var>S</var> to separate lines of text in a <var>TStrings</var> instance.
           </p>
+          <p>
+            The <b>LF</b> (<b>#10</b>) character is used to mark the end of a line in <var>S</var>, and causes the preceeding text to be added to the string list in <var>List</var>. The LF character is not included in the value added to the string list.
+          </p>
+          <p>
+            If no end-of-line characters are found in <var>S</var>, then a single line of text is added to the string list.
+          </p>
         </descr>
         <seealso/>
       </element>
       <element name="StringToStringList.s">
-        <short>String with values extracted and stored in the method</short>
+        <short>String with values extracted and stored in the string list</short>
       </element>
       <element name="StringToStringList.List">
-        <short>TStrings instance where values are stored in the method</short>
+        <short>TStrings instance where values are stored in the routine</short>
       </element>
 
       <element name="GetNextDelimitedItem">
@@ -723,24 +735,48 @@
       </element>
 
       <element name="FindNextDelimitedItem">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Finds the next occurrence of a specific value in a delimited list</short>
+        <descr>
+          <p>
+            <var>FindNextDelimitedItem</var> is a <var>String</var> function used to find the next occurrence of a specific value in a delimited list of values.
+          </p>
+          <p>
+            <var>List</var> is the list with the delimited values searched in the routine.
+          </p>
+          <p>
+            <var>Delimiter</var> is the character used to separate the values in List.
+          </p>
+          <p>
+            <var>Position</var> is a variable parameter with the character index in List where the find operation is started. Position is 1-based, like using indexed access to the values in a String.
+          </p>
+          <p>
+            FindItem is the value to locate in List starting at the given position.
+          </p>
+          <p>
+            FindNextDelimitedItem calls the <var>GetNextDelimitedItem</var> routine to get the individual delimited values in List. GetNextDelimitedItem updates the value in Position when an item is retrieved. The value in Position is set to <b>Len(List)+1</b> if FindItem is not found in the routine.
+          </p>
+          <p>
+            The return value is set to the value in FindItem if it is found in List. The return value is an empty string (<b>''</b>) if FindItem is not found in the List starting at the given position.
+          </p>
+        </descr>
+        <seealso>
+          <link id="GetNextDelimitedItem"/>
+        </seealso>
       </element>
       <element name="FindNextDelimitedItem.Result">
-        <short/>
+        <short>The value in FindItem when found, or an empty string</short>
       </element>
       <element name="FindNextDelimitedItem.List">
-        <short/>
+        <short>List with delimited values examined in the routine</short>
       </element>
       <element name="FindNextDelimitedItem.Delimiter">
-        <short/>
+        <short>Character used to separate values in the list</short>
       </element>
       <element name="FindNextDelimitedItem.Position">
-        <short/>
+        <short>Starting position for the values examined in the routine</short>
       </element>
       <element name="FindNextDelimitedItem.FindItem">
-        <short/>
+        <short>Item value to locate in List</short>
       </element>
 
       <element name="MergeWithDelimiter">
@@ -847,7 +883,7 @@
       </element>
 
       <element name="ReplaceSubstring">
-        <short>Replaces (or appends) values the specified number of bytes at a give position</short>
+        <short>Replaces (or appends) the specified number of bytes at a given position</short>
         <descr>
           <p>
             <var>ReplaceSubstring</var> is a procedure used to replace a portion of a string with the specified value.
@@ -977,10 +1013,18 @@
           <link id="#rtl.sysutils.IsValidIdent">IsValidIdent</link>
         </seealso>
       </element>
-      <element name="LazIsValidIdent.Result"/>
-      <element name="LazIsValidIdent.Ident"/>
-      <element name="LazIsValidIdent.AllowDots"/>
-      <element name="LazIsValidIdent.StrictDots"/>
+      <element name="LazIsValidIdent.Result">
+        <short/>
+      </element>
+      <element name="LazIsValidIdent.Ident">
+        <short/>
+      </element>
+      <element name="LazIsValidIdent.AllowDots">
+        <short/>
+      </element>
+      <element name="LazIsValidIdent.StrictDots">
+        <short/>
+      </element>
 
       <element name="MaxTextLen">
         <short>Defines the maximum length for shortened or "ellipsified" text</short>
@@ -996,6 +1040,5 @@
 
     </module>
     <!-- LazStringUtils -->
-
   </package>
 </fpdoc-descriptions>
docs-lazutils.diff (53,680 bytes)   
docs-lcl.diff (691,621 bytes)

Juha Manninen

2021-02-22 21:55

developer   ~0129108

There is:

-<code>LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s).</code>
+<code>
+ LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s).
+</code>

Many of the changes only add or remove newlines, like :

<code> xxx </code>
vs.
<code>
  xxx
</code>

or

<short> xxx </short>
vs.
<short>
  xxx
</short>

What triggers such a change?

Don Siders

2021-02-23 02:09

reporter   ~0129113

I'm using the Atom editor. It's a by-product of Atom reflowing text blocks.

Juha Manninen

2021-02-23 08:26

developer   ~0129114

Sounds like a bug in Atom editor if you didn't change any settings.
It would be nice to have only real documentation changes in a patch.

What do you say about this :
 LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s)
I guess an automatic doc generator marked such an error and then it stayed.
I don't even know what generator was used.

Don Siders

2021-02-23 12:31

reporter   ~0129120

Let me look at this again. I'll submit new patches.

Don Siders

2021-02-23 15:50

reporter   ~0129122

> Sounds like a bug in Atom editor if you didn't change any settings.

Yeah, it has bugs too.

> It would be nice to have only real documentation changes in a patch.

I have regenerated the diffs to avoid any gratuitous white space changes, The ones in interfacebase.xml are content changes. Micro-managing line endings and whitespace changes isn't much fun.

And yes, I remove the useless XML comments for type visibility. They are always wrong when code gets refactored.

New diffs are attached.

> What do you say about this :
> LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s)
> I guess an automatic doc generator marked such an error and then it stayed.
> I don't even know what generator was used.

Its just an example of the output from the method. Perhaps it should have tagged using PRE. I changed it so it looks less like a real error message, and more like a contrived example.
docs-lazutils-new.diff (49,158 bytes)   
Index: docs/xml/lazutils/lazfileutils.xml
===================================================================
--- docs/xml/lazutils/lazfileutils.xml	(revision 64652)
+++ docs/xml/lazutils/lazfileutils.xml	(working copy)
@@ -19,7 +19,6 @@
         </remark>
       </descr>
 
-    <!-- function Visibility: default -->
       <element name="CompareFilenames">
         <short>
           Gets the relative sort order for the specified file names
@@ -45,22 +44,18 @@
         </seealso>
       </element>
 
-      <!-- function result Visibility: default -->
       <element name="CompareFilenames.Result">
         <short>Relative sort order for the specified file names</short>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="CompareFilenames.Filename1">
         <short>First file name for the comparison</short>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="CompareFilenames.Filename2">
         <short>Second file name for the comparison</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CompareFilenamesIgnoreCase">
         <short>
           Gets the relative sort order for case-insensitive file names
@@ -86,23 +81,16 @@
           <link id="CompareFilenames"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CompareFilenamesIgnoreCase.Result">
         <short>Relative sort order for the file names</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CompareFilenamesIgnoreCase.Filename1">
         <short>First file name for the comparison</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CompareFilenamesIgnoreCase.Filename2">
         <short>Second file name for the comparison</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CompareFileExt">
         <short>
           Performs a sort order comparison for the specified file name and extension
@@ -221,11 +209,25 @@
             Ext can contain the '<b>.</b>' (<b>Period</b>) character used in the extension, but it is not required.
           </p>
           <p>
-            <var>CaseSensitive</var> indicates if case-sensitivity is used when comparing parameter values. When set to <b>True</b>, the comparision is limited to values in the ASCII character set. <var>StrLComp</var> or <var>StrLIComp</var> is called to compare the values in Filename to the values in Ext.
+            <var>CaseSensitive</var> indicates if case-sensitivity is used when comparing parameter values. When set to <b>True</b>, the comparison is limited to values in the ASCII character set. <var>StrLComp</var> or <var>StrLIComp</var> is called to compare the values in Filename to the values in Ext.
           </p>
           <p>
-            The return value is <b>True</b> when Filename uses the file extension in Ext. The return value is <b>False</b> when Filename is an empty string (<b>''</b>), does not include a '<b>.</b>' character that marks the start of the file extension, or does not use the file extension in Ext.
+            The return value is <b>True</b> when Filename uses the file extension in Ext. The return value is <b>False</b> for the following conditions:
           </p>
+          <ul>
+            <li>
+              Filename is an empty string (<b>''</b>).
+            </li>
+            <li>
+              Filename does not have a '<b>.</b>' character that marks the start of the file extension.
+            </li>
+            <li>
+              The extension in Filename has a different length than Ext.
+            </li>
+            <li>
+              Filename has a different file extension than Ext.
+            </li>
+          </ul>
         </descr>
         <seealso>
           <link id="FilenameExtIn"/>
@@ -245,7 +247,7 @@
       </element>
 
       <element name="FilenameExtIn">
-        <short>Determies if the file name uses one of the specified file extensions</short>
+        <short>Determines if the file name uses one of the specified file extensions</short>
         <descr>
           <p>
             <var>FilenameExtIn</var> is a <var>Boolean</var> function used to determine if the file name in the <var>Filename</var> parameter uses one of the file extension in <var>Exts</var>.
@@ -362,7 +364,7 @@
             On Windows, the FilenameIsWinAbsolute function is called in the implementation. FilenameIsWinAbsolute takes Device identifiers into consideration when examining the value in TheFilename. For example:
           </p>
           <code>
-            D:\db\employee.fdb
+D:\db\employee.fdb
           </code>
           <p>
             The return value is False if TheFilename (without the optional device identifier) is an empty string (''), or does not start with the directory separator for the environment.
@@ -370,18 +372,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FilenameIsAbsolute.Result">
         <short>True when the file name is not a relative path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsAbsolute.TheFilename">
         <short>Path and file name to use in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FilenameIsWinAbsolute">
         <short>
           Determines if the specified value is an absolute file path (not a relative one)
@@ -394,7 +391,7 @@
             On Windows, the FilenameIsWinAbsolute function is called in the implementation of FilenameIsAbsolute. FilenameIsWinAbsolute takes Device identifiers into consideration when examine the value in TheFilename. For example:
           </p>
           <code>
-            D:\db\employee.fdb
+D:\db\employee.fdb
           </code>
           <p>
             The return value is False if TheFilename (without the optional device identifier)is an empty string (''), or does not start with the directory separator for the environment.
@@ -402,18 +399,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FilenameIsWinAbsolute.Result">
         <short>True when the file name is not a relative path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsWinAbsolute.TheFilename">
         <short>Path and file name to use in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FilenameIsUnixAbsolute">
         <short>
           Determines if the specified value is an absolute file path (not a relative one)
@@ -428,13 +420,9 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FilenameIsUnixAbsolute.Result">
         <short>True when the file name is not a relative path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsUnixAbsolute.TheFilename">
         <short>Path and file name to use in the function</short>
       </element>
@@ -445,7 +433,7 @@
         </short>
         <descr>
           <p>
-            <var>ForceDirectory</var>  is a Boolean function which creates the specified directory if it does not already exist. ForceDirectory ensures that a trailing path delimiter exists in <var>DirectoryName</var> prior to checking the file system. Duplicate adjacent path delimiters (like '//foo//bar/foobar/' or '\\foo\\bar\foobar\') are removed prior to checking the directory path.
+            <var>ForceDirectory</var> is a Boolean function which creates the specified directory if it does not already exist. ForceDirectory ensures that a trailing path delimiter exists in <var>DirectoryName</var> prior to checking the file system. Duplicate adjacent path delimiters (like '//foo//bar/foobar/' or '\\foo\\bar\foobar\') are removed prior to checking the directory path.
           </p>
           <p>
             Each directory in the specified path is validated by calling <var>DirPathExists</var>. ForceDirectory calls <var>CreateDirUTF8</var> if a directory does not exist, and may exit with a return value of <b>False</b> if directory creation is not successful.
@@ -467,7 +455,6 @@
         <short>Path information for the operation</short>
       </element>
 
-      <!-- procedure Visibility: default -->
       <element name="CheckIfFileIsExecutable">
         <short>
           Examines the specified file to see if it is executable
@@ -523,13 +510,10 @@
           </dl>
         </errors>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CheckIfFileIsExecutable.AFilename">
         <short>File name to examine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsExecutable">
         <short>
           Determines if the specified file name is executable
@@ -541,13 +525,9 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsExecutable.Result">
         <short>True if the file is executable on the platform or OS</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsExecutable.AFilename">
         <short>File name to examine</short>
       </element>
@@ -601,7 +581,6 @@
         <short>File name examined in the routine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsReadable">
         <short>
           Indicates if the specified file name is readable
@@ -616,18 +595,13 @@
           <link id="#rtl.baseunix.FpAccess">FpAccess</link>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsReadable.Result">
         <short>True when the specified file name is readable</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsReadable.AFilename">
         <short>File name to examine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsWritable">
         <short>
           Indicates if the specified file name is writable
@@ -634,23 +608,18 @@
         </short>
         <descr>
           <p>
-            FileIsWritable is a Boolean function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file.
+            <var>FileIsWritable</var> is a <var>Boolean</var> function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file.
           </p>
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsWritable.Result">
         <short>True when the specified file name is writable</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsWritable.AFilename">
         <short>File name to examine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsText">
         <short>
           Determines if the specified file contains plain text content
@@ -657,7 +626,7 @@
       </short>
         <descr>
           <p>
-            FileIsText is a Boolean function used to determine if the specified file contains plain text content. The overloaded variant that includes the FileReadable argument is used to examine the content in the file.
+            <var>FileIsText</var> is a <var>Boolean</var> function used to determine if the specified file contains plain text content. The overloaded variant that includes the FileReadable argument is used to examine the content in the file.
           </p>
           <p>
             FileIsText calls FileOpenUtf8 for the specified file name. The return value is False is the file handle contains feInvalidHandle.
@@ -676,28 +645,21 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsText.Result">
         <short>True when the file contains plain text content</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsText.AFilename">
         <short>File name to examine in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsText.FileReadable">
         <short>Indicates if the specified file was successfully opened and read</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FilenameIsTrimmed">
         <short/>
         <descr>
           <p>
-            FilenameIsTrimmed is an overloaded Boolean function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The  return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters.
+            <var>FilenameIsTrimmed</var> is an overloaded <var>Boolean</var> function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The  return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters.
           </p>
           <p>
             Use TrimFilename to remove leading or trailing whitespace, duplicate directory separators, or relative path symbols.
@@ -705,34 +667,25 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FilenameIsTrimmed.Result">
         <short>False when the file name needs to trimmed</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsTrimmed.TheFilename">
         <short>File name to examine in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsTrimmed.StartPos">
         <short>PChar with the file name value</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FilenameIsTrimmed.NameLen">
         <short>Length of the file name</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="TrimFilename">
         <short>
           Removes leading and trailing spaces, and resolves special characters
         </short>
         <descr>
-          <var>TrimFilename</var> is a String function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//').
+          <var>TrimFilename</var> is a <var>String</var> function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//').
         </descr>
         <errors/>
         <seealso>
@@ -744,13 +697,9 @@
           <link id="TrimAndExpandDirectory"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="TrimFilename.Result">
         <short>New value  for the path and file name</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimFilename.AFilename">
         <short>Path and file name for the operation</short>
       </element>
@@ -772,7 +721,6 @@
         <short>File name examined in the routine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CleanAndExpandFilename">
         <short>
           Removes whitespace and resolves special characters in the specified file name
@@ -779,23 +727,18 @@
         </short>
         <descr>
           <p>
-            CleanAndExpandFilename is a String function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string ('').
+            <var>CleanAndExpandFilename</var> is a <var>String</var> function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string ('').
           </p>
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CleanAndExpandFilename.Result">
         <short>File name with whitespace removed and special characters resolved</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CleanAndExpandFilename.Filename">
         <short>File name to examine in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CleanAndExpandDirectory">
         <short>
           Removes whitespace and resolves special characters in the specified path
@@ -810,20 +753,15 @@
           <link id="AppendPathDelim"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CleanAndExpandDirectory.Result">
         <short>
           Path information after removing whitespace and resolving special characters
         </short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CleanAndExpandDirectory.Filename">
         <short>Path information for the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="TrimAndExpandFilename">
         <short>
           Cleans and resolves a file path to the specified base directory name
@@ -838,23 +776,16 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="TrimAndExpandFilename.Result">
         <short>Cleaned and resolved file path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimAndExpandFilename.Filename">
         <short>File name for the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimAndExpandFilename.BaseDir">
         <short>Base directory name used for a relative file path</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="TrimAndExpandDirectory">
         <short>
           Cleans and resolves a relative path to a base directory
@@ -872,23 +803,16 @@
           <link id="TrimFilename"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="TrimAndExpandDirectory.Result">
         <short>Path information cleaned and resolved to the specified base directory</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimAndExpandDirectory.Filename">
         <short>Path information for the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="TrimAndExpandDirectory.BaseDir">
         <short>Base directory used to resolve a relative path</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CreateRelativePath">
         <short>
           Creates a relative path from BaseDirectory to Filename
@@ -906,23 +830,15 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CreateRelativePath.Result">
         <short>Relative path from the base directory for the file name</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CreateRelativePath.Filename">
         <short>File name for the operation</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CreateRelativePath.BaseDirectory">
         <short>Base directory for the relative path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CreateRelativePath.UsePointDirectory">
         <short>
           True if '.' (current directory symbol) is prepended to the relative path
@@ -929,7 +845,6 @@
         </short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsInPath">
         <short>
           Returns True if Filename exists in the specified Path
@@ -953,18 +868,12 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsInPath.Result">
         <short>True when the file exists in the specified path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsInPath.Filename">
         <short>File name to locate</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsInPath.Path">
         <short>Path used for the operation</short>
       </element>
@@ -1012,7 +921,7 @@
         <seealso/>
       </element>
       <element name="ShortDisplayFilename.Result">
-        <short>Shortened version of the specifed file name</short>
+        <short>Shortened version of the specified file name</short>
       </element>
       <element name="ShortDisplayFilename.aFileName">
         <short>File name examined in the routine</short>
@@ -1091,7 +1000,6 @@
         <short>File name examined in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="AppendPathDelim">
         <short>
           Adds a trailing path delimiter when needed
@@ -1103,18 +1011,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="AppendPathDelim.Result">
         <short>Path value with a trailing path delimiter</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="AppendPathDelim.Path">
         <short>Path value to examine</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="ChompPathDelim">
         <short>
           Removes a trailing path delimiter from the specified value
@@ -1126,13 +1029,9 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="ChompPathDelim.Result">
         <short>Path information after removing the trailing path delimiter</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="ChompPathDelim.Path">
         <short>Path information for the function</short>
       </element>
@@ -1392,7 +1291,6 @@
         <short>Length in characters for the search paths list</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileExistsUTF8">
         <short>
           Indicates if the specified file name exists
@@ -1405,17 +1303,14 @@
         <seealso/>
       </element>
 
-      <!-- function result Visibility: default -->
       <element name="FileExistsUTF8.Result">
         <short>True when the specified file name exists</short>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="FileExistsUTF8.Filename">
         <short>UTF-8-encoded file name to locate in the local file system</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileAgeUTF8">
         <short>
           Returns the last modification time for the file in FileDate format
@@ -1433,18 +1328,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileAgeUTF8.Result">
         <short>Last modification time for the file in FileDate format</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileAgeUTF8.FileName">
         <short>File name examined in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="DirectoryExistsUTF8">
         <short>
           Determine if the specified path exists on the local file system
@@ -1456,18 +1346,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="DirectoryExistsUTF8.Result">
         <short>True when the directory exists in the file system</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="DirectoryExistsUTF8.Directory">
         <short>Directory name to locate in the file system</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="ExpandFileNameUTF8">
         <short>
           Expands the values in FileName and BaseDir to an absolute file name
@@ -1486,23 +1371,16 @@
           <link id="ResolveDots"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="ExpandFileNameUTF8.Result">
         <short>The file name with an absolute path</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="ExpandFileNameUTF8.FileName">
         <short>File name examined in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="ExpandFileNameUTF8.BaseDir">
         <short>Base directory used to resolve a relative path</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FindFirstUTF8">
         <short>
           Starts searching for files matching the specified path value
@@ -1523,28 +1401,19 @@
           <link id="#rtl.sysutils.FindFirst">FindFirst</link>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FindFirstUTF8.Result">
         <short>Last error number encountered in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FindFirstUTF8.Path">
         <short>Path and/or file name to locate</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FindFirstUTF8.Attr">
         <short>File attributes to include in the search</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FindFirstUTF8.Rslt">
         <short>Search record for the first matching file</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FindNextUTF8">
         <short>
           Locates another file matching the search criteria
@@ -1562,18 +1431,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FindNextUTF8.Result">
         <short>Last error number</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FindNextUTF8.Rslt">
         <short>Search criteria for the function</short>
       </element>
 
-      <!-- procedure Visibility: default -->
       <element name="FindCloseUTF8">
         <short>
           Frees resources allocated to the specified search record
@@ -1586,12 +1450,10 @@
         <seealso/>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="FindCloseUTF8.F">
         <short>Search record to free in the procedure</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileSetDateUTF8">
         <short>
           Sets the last modification time for the file
@@ -1609,23 +1471,16 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileSetDateUTF8.Result">
         <short>Last error number in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSetDateUTF8.FileName">
         <short>File name to update in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSetDateUTF8.Age">
         <short>New value for the last modification time</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileGetAttrUTF8">
           <short>
             Gets the value of file attributes for the specified file name
@@ -1666,18 +1521,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileGetAttrUTF8.Result">
         <short>File attribute value for the specified file name</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileGetAttrUTF8.FileName">
         <short>File name for the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileSetAttrUTF8">
         <short>
           Sets the file attribute value for the specified file name
@@ -1721,23 +1571,16 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileSetAttrUTF8.Result">
         <short>Last error number from the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSetAttrUTF8.Filename">
         <short>File name to update in the function</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSetAttrUTF8.Attr">
         <short>File attribute value for the specified file name</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="DeleteFileUTF8">
         <short>
           Deletes the specified file name
@@ -1755,18 +1598,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="DeleteFileUTF8.Result">
         <short>True if the specified file name is deleted</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="DeleteFileUTF8.FileName">
         <short>File name to delete in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="RenameFileUTF8">
         <short>
           Renames a file to the specified value
@@ -1785,23 +1623,16 @@
         <errors/>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="RenameFileUTF8.Result">
         <short>True if the file is successfully renamed to the new value</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="RenameFileUTF8.OldName">
         <short>Existing name for the file</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="RenameFileUTF8.NewName">
         <short>New name for the file</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileSearchUTF8">
         <short>
           Searches for a file with the specified name in the list of directory paths
@@ -1822,23 +1653,16 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileSearchUTF8.Result">
         <short>Path and file name for the matching file, or an empty string</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSearchUTF8.Name">
         <short>File name to locate in the list of directory paths</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileSearchUTF8.DirList">
         <short>The delimited list of directory paths to search</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="FileIsReadOnlyUTF8">
         <short>
           Determines if the specified file is marked as read-only
@@ -1850,18 +1674,13 @@
         </descr>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="FileIsReadOnlyUTF8.Result">
         <short>True when the file is marked as read-only</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="FileIsReadOnlyUTF8.FileName">
         <short>File name to examine in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="GetCurrentDirUTF8">
         <short>
           Gets the name for the current directory
@@ -1881,13 +1700,10 @@
           <link id="#rtl.sysutils.GetCurrentDir">GetCurrentDir</link>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="GetCurrentDirUTF8.Result">
         <short>Name for the current directory</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="SetCurrentDirUTF8">
         <short>
           Sets the current directory to the specified name
@@ -1916,18 +1732,13 @@
         </errors>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="SetCurrentDirUTF8.Result">
         <short>True if the current directory was successfully changed to the new value</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="SetCurrentDirUTF8.NewDir">
         <short>Directory name to use as the current directory</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="CreateDirUTF8">
         <short>
           Creates a new directory with the specified name
@@ -1947,18 +1758,13 @@
         </errors>
         <seealso/>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="CreateDirUTF8.Result">
         <short>True if the new directory is successfully created</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="CreateDirUTF8.NewDir">
         <short>Name for the new directory</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="RemoveDirUTF8">
         <short>
           Removes the directory with the specified name
@@ -1981,18 +1787,13 @@
           <link id="#rtl.sysutils.RemoveDir">RemoveDir</link>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="RemoveDirUTF8.Result">
         <short>True when the directory is successfully removed</short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="RemoveDirUTF8.Dir">
         <short>Name of the directory to remove in the function</short>
       </element>
 
-      <!-- function Visibility: default -->
       <element name="ForceDirectoriesUTF8">
         <short>
           Creates the specified directories if they do not already exist
@@ -1999,7 +1800,7 @@
         </short>
         <descr>
           <p>
-            <var>ForceDirectories</var>  is a <var>Boolean</var> function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function.
+            <var>ForceDirectories</var> is a <var>Boolean</var> function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function.
           </p>
           <p>
             ForceDirectories raises an <var>EInOutError</var> exception with the message in <var>SCannotCreateEmptyDir</var> when Dir contains an empty string ('').
@@ -2020,15 +1821,11 @@
           <link id="ForceDirectory"/>
         </seealso>
       </element>
-
-      <!-- function result Visibility: default -->
       <element name="ForceDirectoriesUTF8.Result">
         <short>
           True when directories exist or are successfully created in the function
         </short>
       </element>
-
-      <!-- argument Visibility: default -->
       <element name="ForceDirectoriesUTF8.Dir">
         <short>Path information to examine the function</short>
       </element>
@@ -2151,7 +1948,7 @@
             For the Amiga platform, the content in the return value is derived using a  TFileInfoBlock for a shared lock on the file. The return value can be an empty string if the file could not be locked using a shared lock on the file system. It can contain values like the following:
           </p>
         <code>
- asperwd
+asperwd
         </code>
         <dl>
           <dt>a</dt>
@@ -2172,9 +1969,7 @@
         <p>
           For Windows platforms, the return value contains only the modification date/time for the file using the format:
         </p>
-        <code>
-Modified: MM/DD/YYYY hh:mm
-        </code>
+        <code>Modified: MM/DD/YYYY hh:mm</code>
         <p>
           The return value can be 'Modified: ?' if an exception is encountered when getting the date/time value for the file.
         </p>
@@ -2414,7 +2209,7 @@
             If the directory does not exist and Create contains True, the <var>ForceDirectoriesUTF8</var> routine is called to create any missing directories for the path. An <var>EInOutError</var> exception is raised if any missing directory in the path cannot be created.
           </p>
           <p>
-            GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help viewer  (LHelp).
+            GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help viewer (LHelp).
           </p>
         </descr>
         <seealso>
@@ -2572,7 +2367,7 @@
             ExtractUNCVolume calls the <var>IsUNCPath</var> function to determine if the value in <var>Path</var> starts with the UNC naming delimiters. The return value is an empty string (<b>''</b>), and no additional actions are performed in the function, when Path does not use UNC notation.
           </p>
           <p>
-            ExtractUNCVolume examines the characters in Path to determine if it uses the long or the short format for UNC notation. Long format notation begins with the characters <b>'\\?\'</b>  or <b>'\\?\UNC\'</b> followed by a drive designation and optional path information such as 'c:\'. Short format notation uses a host name and a shared resource identifier such as <b>'\\mypc\nas-drive\'</b>.
+            ExtractUNCVolume examines the characters in Path to determine if it uses the long or the short format for UNC notation. Long format notation begins with the characters <b>'\\?\'</b> or <b>'\\?\UNC\'</b> followed by a drive designation and optional path information such as 'c:\'. Short format notation uses a host name and a shared resource identifier such as <b>'\\mypc\nas-drive\'</b>.
           </p>
         </descr>
         <seealso>
@@ -2739,7 +2534,6 @@
         <short>Command line option examined in the function</short>
       </element>
 
-      <!-- procedure type Visibility: default -->
       <element name="TInvalidateFileStateCacheEvent">
         <short>
           Specifies the event signalled for an invalid file state in the file cache
@@ -2755,12 +2549,10 @@
         </seealso>
       </element>
 
-      <!-- argument Visibility: default -->
       <element name="TInvalidateFileStateCacheEvent.Filename">
         <short>File name for the event notification</short>
       </element>
 
-      <!-- variable Visibility: default -->
       <element name="OnInvalidateFileStateCache">
         <short>
           Implements the event handler for a file with an invalid file state
@@ -2778,7 +2570,6 @@
         </seealso>
       </element>
 
-      <!-- procedure Visibility: default -->
       <element name="InvalidateFileStateCache">
         <short>
           Signals the OnInvalidateFileStateCache event handler
Index: docs/xml/lazutils/lazstringutils.xml
===================================================================
--- docs/xml/lazutils/lazstringutils.xml	(revision 64652)
+++ docs/xml/lazutils/lazstringutils.xml	(working copy)
@@ -81,10 +81,10 @@
       </element>
 
       <element name="PosI">
-        <short>A case-insensitive version of the Pos routine</short>
+        <short>A case-insensitive optimized version of the Pos routine</short>
         <descr>
           <p>
-            <var>PosI</var> implements a case-insensitive version of the <var>Pos</var> routine found the RTL <file>system</file> unit. It only accepts <var>String</var> values in its parameters, unlike the RTL overloaded variants which accept combinations of the Char, ShortString, AnsiString, UnicodeString, WideString, and Variant types.
+            <var>PosI</var> implements a case-insensitive optimized version of the <var>Pos</var> routine found the RTL <file>system</file> unit. It only accepts <var>String</var> values in its parameters, unlike the RTL overloaded variants which accept combinations of the Char, ShortString, AnsiString, UnicodeString, WideString, and Variant types.
           </p>
           <p>
             It is also an alternative to the <var>ContainsText</var> routine in the RTL <file>StrUtils</file> unit, which has a <b>very</b> slow implementation.
@@ -105,7 +105,7 @@
         </seealso>
       </element>
       <element name="PosI.Result">
-        <short>Positionof the sub-string witin the searched value, or 0 when not found</short>
+        <short>Position of the sub-string within the searched value, or 0 when not found</short>
       </element>
       <element name="PosI.SubStr">
         <short>Value to locate in the searched value</short>
@@ -236,7 +236,9 @@
       </element>
 
       <element name="LineBreaksToDelimiter">
-        <short>Converts CR or LF characters in a string to the specified delimiter character</short>
+        <short>
+          Converts CR or LF characters in a string to the specified delimiter character
+        </short>
         <descr/>
         <seealso/>
       </element>
@@ -251,11 +253,13 @@
       </element>
 
       <element name="ConvertLineEndings">
-        <short/>
+        <short>Deprecated</short>
         <descr>
           <remark>Deprecated. Use LineBreaksToSystemLineBreaks instead.</remark>
         </descr>
-        <seealso/>
+        <seealso>
+          <link id="LineBreaksToSystemLineBreaks"/>
+        </seealso>
       </element>
       <element name="ConvertLineEndings.Result">
         <short/>
@@ -437,7 +441,7 @@
           <p>
             <var>BeautifyLineXY</var> is a <var>String</var> function used to combine the values in the <var>Filename</var>, <var>Line</var>, <var>X</var> and <var>Y</var> arguments into a formatted message. The message is in the form:
           </p>
-<code>LazStringUtils.pas (742, 1) Invalid UTF-8 codepoint found in the specified argument(s).</code>
+<code>examplefile.pas (123, 1) The error message goes here.</code>
           <p>
             <var>Filename</var> contains a file name used at the start of the formatted message.
           </p>
@@ -634,19 +638,25 @@
       </element>
 
       <element name="StringToStringList">
-        <short>Stores the specified string as lines in a TStrings instance</short>
+        <short>Stores a multi-line string as seperate lines in a TStrings instance</short>
         <descr>
           <p>
-            <b>LF</b> (<b>#10</b>) characters found in <var>s</var> control when a line of text is added in the <var>TStrings</var> instance. The end-of-line character is not stored in the TStrings instance. If no end-of-line characters are found in S, then a single line of text is added to the string list.
+            <var>StringToStringList</var> is a procedure used to convert the multi-line String in <var>S</var> to separate lines of text in a <var>TStrings</var> instance.
           </p>
+          <p>
+            The <b>LF</b> (<b>#10</b>) character is used to mark the end of a line in <var>S</var>, and causes the preceeding text to be added to the string list in <var>List</var>. The LF character is not included in the value added to the string list.
+          </p>
+          <p>
+            If no end-of-line characters are found in <var>S</var>, then a single line of text is added to the string list.
+          </p>
         </descr>
         <seealso/>
       </element>
       <element name="StringToStringList.s">
-        <short>String with values extracted and stored in the method</short>
+        <short>String with values extracted and stored in the string list</short>
       </element>
       <element name="StringToStringList.List">
-        <short>TStrings instance where values are stored in the method</short>
+        <short>TStrings instance where values are stored in the routine</short>
       </element>
 
       <element name="GetNextDelimitedItem">
@@ -723,24 +733,48 @@
       </element>
 
       <element name="FindNextDelimitedItem">
-        <short/>
-        <descr/>
-        <seealso/>
+        <short>Finds the next occurrence of a specific value in a delimited list</short>
+        <descr>
+          <p>
+            <var>FindNextDelimitedItem</var> is a <var>String</var> function used to find the next occurrence of a specific value in a delimited list of values.
+          </p>
+          <p>
+            <var>List</var> is the list with the delimited values searched in the routine.
+          </p>
+          <p>
+            <var>Delimiter</var> is the character used to separate the values in List.
+          </p>
+          <p>
+            <var>Position</var> is a variable parameter with the character index in List where the find operation is started. Position is 1-based, like using indexed access to the values in a String.
+          </p>
+          <p>
+            FindItem is the value to locate in List starting at the given position.
+          </p>
+          <p>
+            FindNextDelimitedItem calls the <var>GetNextDelimitedItem</var> routine to get the individual delimited values in List. GetNextDelimitedItem updates the value in Position when an item is retrieved. The value in Position is set to <b>Len(List)+1</b> if FindItem is not found in the routine.
+          </p>
+          <p>
+            The return value is set to the value in FindItem if it is found in List. The return value is an empty string (<b>''</b>) if FindItem is not found in the List starting at the given position.
+          </p>
+        </descr>
+        <seealso>
+          <link id="GetNextDelimitedItem"/>
+        </seealso>
       </element>
       <element name="FindNextDelimitedItem.Result">
-        <short/>
+        <short>The value in FindItem when found, or an empty string</short>
       </element>
       <element name="FindNextDelimitedItem.List">
-        <short/>
+        <short>List with delimited values examined in the routine</short>
       </element>
       <element name="FindNextDelimitedItem.Delimiter">
-        <short/>
+        <short>Character used to separate values in the list</short>
       </element>
       <element name="FindNextDelimitedItem.Position">
-        <short/>
+        <short>Starting position for the values examined in the routine</short>
       </element>
       <element name="FindNextDelimitedItem.FindItem">
-        <short/>
+        <short>Item value to locate in List</short>
       </element>
 
       <element name="MergeWithDelimiter">
@@ -847,7 +881,7 @@
       </element>
 
       <element name="ReplaceSubstring">
-        <short>Replaces (or appends) values the specified number of bytes at a give position</short>
+        <short>Replaces (or appends) the specified number of bytes at a given position</short>
         <descr>
           <p>
             <var>ReplaceSubstring</var> is a procedure used to replace a portion of a string with the specified value.
docs-lazutils-new.diff (49,158 bytes)   
docs-lcl-new.diff (622,677 bytes)

Juha Manninen

2021-02-24 09:35

developer   ~0129136

Applied, thanks.
Ok, I understand the example output line now. :)

Issue History

Date Modified Username Field Change
2021-02-22 16:09 Don Siders New Issue
2021-02-22 16:09 Don Siders File Added: docs-lazutils.diff
2021-02-22 16:09 Don Siders File Added: docs-lcl.diff
2021-02-22 21:47 Juha Manninen Assigned To => Juha Manninen
2021-02-22 21:47 Juha Manninen Status new => assigned
2021-02-22 21:55 Juha Manninen Note Added: 0129108
2021-02-23 02:09 Don Siders Note Added: 0129113
2021-02-23 08:26 Juha Manninen Note Added: 0129114
2021-02-23 12:31 Don Siders Note Added: 0129120
2021-02-23 15:50 Don Siders Note Added: 0129122
2021-02-23 15:50 Don Siders File Added: docs-lazutils-new.diff
2021-02-23 15:50 Don Siders File Added: docs-lcl-new.diff
2021-02-24 09:35 Juha Manninen Status assigned => resolved
2021-02-24 09:35 Juha Manninen Resolution open => fixed
2021-02-24 09:35 Juha Manninen Fixed in Revision => r64658
2021-02-24 09:35 Juha Manninen LazTarget => -
2021-02-24 09:35 Juha Manninen Note Added: 0129136
2021-02-24 10:30 Don Siders Status resolved => closed