Add comments about parameter normalization

Author: paulirwin

src/Lucene.Net.Analysis.Common/Analysis/Core/StopAnalyzer.cs

@@ -83,7 +83,7 @@ public StopAnalyzer(LuceneVersion matchVersion, CharArraySet stopWords)
         /// Builds an analyzer with the stop words from the given file. </summary>
         /// <seealso cref="WordlistLoader.GetWordSet(TextReader, LuceneVersion)"/>
         /// <param name="matchVersion"> See <see cref="LuceneVersion"/> </param>
-        /// <param name="stopwordsFileName"> File name to load stop words from  </param>
+        /// <param name="stopwordsFileName"> File name to load stop words from. The path is not normalized by this method. </param>
         /// <remarks>
         /// LUCENENET: This overload takes a string file name to avoid allocating a <see cref="FileInfo"/> object.
         /// </remarks>

src/Lucene.Net.Analysis.Common/Analysis/Util/FilesystemResourceLoader.cs

@@ -58,6 +58,10 @@ public FilesystemResourceLoader()
         /// Files not found in file system and class lookups are delegated to context
         /// classloader.
         /// </summary>
+        /// <param name="baseDirectory">The base directory path. The path is not normalized by this method.</param>
+        /// <remarks>
+        /// LUCENENET: This overload takes a string to avoid allocating a <see cref="DirectoryInfo"/> object.
+        /// </remarks>
         public FilesystemResourceLoader(string? baseDirectory)
             : this(baseDirectory, new ClasspathResourceLoader(typeof(FilesystemResourceLoader)))
         {
@@ -91,6 +95,11 @@ public FilesystemResourceLoader(DirectoryInfo? baseDirectory, IResourceLoader @d
         /// Files not found in file system and class lookups are delegated
         /// to the given delegate <see cref="IResourceLoader"/>.
         /// </summary>
+        /// <param name="baseDirectory">The base directory path. The path is not normalized by this method.</param>
+        /// <param name="delegate">The delegate resource loader.</param>
+        /// <remarks>
+        /// LUCENENET: This overload takes a string to avoid allocating a <see cref="DirectoryInfo"/> object.
+        /// </remarks>
         public FilesystemResourceLoader(string? baseDirectory, IResourceLoader @delegate)
         {
             // LUCENENET NOTE: If you call DirectoryInfo.Create() it doesn't set the DirectoryInfo.Exists

src/Lucene.Net.Analysis.Common/Analysis/Util/StopwordAnalyzerBase.cs

@@ -109,9 +109,7 @@ protected static CharArraySet LoadStopwordSet(bool ignoreCase, Type aClass, stri
         /// <summary>
         /// Creates a <see cref="CharArraySet"/> from a file.
         /// </summary>
-        /// <param name="stopwordsFileName">
-        ///          the stopwords file name to load
-        /// </param>
+        /// <param name="stopwordsFileName">The file name to load stopwords from. The path is not normalized by this method.</param>
         /// <param name="matchVersion">
         ///          the Lucene version for cross version compatibility </param>
         /// <returns> a <see cref="CharArraySet"/> containing the distinct stopwords from the given

src/Lucene.Net.Benchmark/ByTask/Tasks/WriteEnwikiLineDocTask.cs

@@ -44,7 +44,10 @@ public WriteEnwikiLineDocTask(PerfRunData runData)
         }
 
         /// <summary>Compose categories line file out of original line file</summary>
-        // LUCENENET specific: changed to use string fileName instead of allocating a FileInfo (#832)
+        /// <param name="fileName">The file name. The path is not normalized by this method.</param>
+        /// <remarks>
+        /// LUCENENET: This overload takes a string fileName instead of allocating a FileInfo.
+        /// </remarks>
         public static string CategoriesLineFile(string fileName)
         {
             string dir = Path.GetDirectoryName(fileName);

src/Lucene.Net.Benchmark/ByTask/Utils/FileUtils.cs

@@ -36,7 +36,7 @@ public static bool FullyDelete(DirectoryInfo dir)
         /// <summary>
         /// Delete files and directories, even if non-empty.
         /// </summary>
-        /// <param name="dirName">Directory path to delete.</param>
+        /// <param name="dirName">Directory path to delete. The path is not normalized by this method.</param>
         /// <returns><c>true</c> on success, <c>false</c> if no or part of files have been deleted.</returns>
         /// <exception cref="IOException">If there is a low-level I/O error.</exception>
         /// <remarks>

src/Lucene.Net.Benchmark/ByTask/Utils/StreamUtils.cs

@@ -47,6 +47,7 @@ public static class StreamUtils // LUCENENET specific: CA1052 Static holder type
         /// based on the file name (e.g., if it ends with .bz2 or .bzip, return a
         /// 'bzip' <see cref="Stream"/>).
         /// </summary>
+        /// <param name="fileName">The file name. The path is not normalized by this method.</param>
         /// <remarks>
         /// LUCENENET: This overload takes a string file name to avoid allocating a <see cref="FileInfo"/> object.
         /// </remarks>
@@ -83,6 +84,7 @@ private static FileType GetFileType(string fileName)
         /// Returns an <see cref="Stream"/> over the requested file, identifying
         /// the appropriate <see cref="Stream"/> instance similar to <see cref="GetInputStream(string)"/>.
         /// </summary>
+        /// <param name="fileName">The file name. The path is not normalized by this method.</param>
         /// <remarks>
         /// LUCENENET: This overload takes a string file name to avoid allocating a <see cref="FileInfo"/> object.
         /// </remarks>

src/Lucene.Net.Suggest/Spell/PlainTextDictionary.cs

@@ -42,6 +42,7 @@ public class PlainTextDictionary : IDictionary
         /// NOTE: content is treated as UTF-8
         /// </para>
         /// </summary>
+        /// <param name="fileName">The file name. The path is not normalized by this method.</param>
         /// <remarks>
         /// LUCENENET: This overload takes a string to avoid having to allocate a <see cref="FileInfo"/> object.
         /// </remarks>

src/Lucene.Net.Suggest/Suggest/Jaspell/JaspellTernarySearchTrie.cs

@@ -233,7 +233,7 @@ public JaspellTernarySearchTrie(FileInfo file)
         /// <para>Uses the culture of the current thread to lowercase words before comparing.</para>
         /// </summary>
         /// <param name="fileName">
-        ///          The file name with the data to load into the Trie. </param>
+        ///          The file name with the data to load into the Trie. The path is not normalized by this method. </param>
         /// <exception cref="IOException">
         ///              A problem occured while reading the data. </exception>
         /// <remarks>
@@ -268,7 +268,7 @@ public JaspellTernarySearchTrie(FileInfo file, CultureInfo culture)
         /// <para>Uses the supplied culture to lowercase words before comparing.</para>
         /// </summary>
         /// <param name="fileName">
-        ///          The file name with the data to load into the Trie. </param>
+        ///          The file name with the data to load into the Trie. The path is not normalized by this method. </param>
         /// <param name="culture">The culture used for lowercasing.</param>
         /// <exception cref="IOException">
         ///              A problem occured while reading the data. </exception>
@@ -305,7 +305,7 @@ public JaspellTernarySearchTrie(FileInfo file, bool compression)
         /// <para>Uses the culture of the current thread to lowercase words before comparing.</para>
         /// </summary>
         /// <param name="fileName">
-        ///          The file name with the data to load into the Trie. </param>
+        ///          The file name with the data to load into the Trie. The path is not normalized by this method. </param>
         /// <param name="compression">
         ///          If true, the file is compressed with the GZIP algorithm, and if
         ///          false, the file is a normal text document. </param>
@@ -356,7 +356,7 @@ public JaspellTernarySearchTrie(FileInfo file, bool compression, CultureInfo cul
         /// </para>
         /// </summary>
         /// <param name="fileName">
-        ///          The file name with the data to load into the Trie. </param>
+        ///          The file name with the data to load into the Trie. The path is not normalized by this method. </param>
         /// <param name="compression">
         ///          If true, the file is compressed with the GZIP algorithm, and if
         ///          false, the file is a normal text document. </param>

src/Lucene.Net/Util/Fst/FST.cs

@@ -567,6 +567,7 @@ public void Save(DataOutput @out)
         /// <summary>
         /// Writes an automaton to a file.
         /// </summary>
+        /// <param name="fileName">The file name. The path is not normalized by this method.</param>
         /// <remarks>
         /// LUCENENET: This overload takes a string file name to avoid allocating a <see cref="FileInfo"/> object.
         /// </remarks>

src/Lucene.Net/Util/IOUtils.cs

@@ -492,9 +492,12 @@ public static TextReader GetDecodingReader(Stream stream, Encoding charSet)
         /// Decoding readers are useful to load configuration files, stopword lists or synonym files
         /// to detect character set problems. However, its not recommended to use as a common purpose
         /// reader. </summary>
-        /// <param name="fileName"> The file name to open a reader on </param>
+        /// <param name="fileName"> The file name to open a reader on. The path is not normalized by this method. </param>
         /// <param name="charSet"> The expected charset </param>
         /// <returns> A reader to read the given file </returns>
+        /// <remarks>
+        /// LUCENENET: This overload takes a string file name to avoid allocating a <see cref="FileInfo"/> object.
+        /// </remarks>
         public static TextReader GetDecodingReader(string fileName, Encoding charSet)
         {
             FileStream stream = null;