#80 Cleanup: doc comment gaps, ISSUES.md numbers in comments, misplaced test, fuzzy .po guesses

[Thomas Mueller]

Small points found by a code review, mostly documentation; only the DUnitFolderIterator one changes behaviour.

Doc comments

• u_dzFileUtils: TSimpleDirEnumerator.Execute has no @param for Mask, MayHaveAttr and HandleHidden; TFileSystem.FindMatchingDirs, FindMatchingDir, FindMatchingFile, MatchingFileExists and AssertMatchingFileExists have none for HandleHidden, although it decides whether hidden and system entries are found (default: not). The summary of MatchingFileExists names only directories as ignored, and its @param Filename says "the first matching file" without the note FindMatchingFile has, that this is not deterministic.
• u_dzFileUtils: with Recursive = True, TSimpleDirEnumerator.Execute applies MayHaveAttr only to the top directory; below it, it enumerates files only (EnumFilesOnly). With the default ALL_FILES_ATTRIB_SET, the top level therefore returns matching directories as well, the subdirectories do not. Not documented.
• u_dzVariantUtils: the doc comment of TryVar2DateTime says the range check applies to "anything else, e.g. a number", but strings are range-checked too (TryStr2DateTime(_v, _dt) and IsFormattableDateTime(_dt)). It, Var2DateTimeStr and Var2DateStr list the Windows, German and ISO 8601 formats, but not the UK format TryStr2DateTime accepts since features #35.
• u_dzDbCreatorCreateAccess: TAccessDbCreator.CompressDatabase calls TFileSystem.CreateUniqueTempDir, but its doc comment has no @raises ECreateUniqueDir.
• u_dzCsvWriter, u_dzFixedWidthTextWriter: the note that the output is written through the ANSI code page is an implementation comment above WriteCaptionsToStream only. WriteLineToStream writes the same way, and neither declaration has a doc comment saying so.

ISSUES.md numbers in comments

Comments are not supposed to name ISSUES.md entries. 71 lines in 16 versioned files still do, among them src/u_dzDefaultMain.pas:491 ("since issue 86"), compiletests/AllUnits/BuildForVersion.cmd (4), UnitTests/_Harness/readme.txt (14), and test comments and check messages such as EXPECTED TO FAIL until ISSUES.md 56 is fixed in testGuidUtils (23 lines), testNameValueList / testUnsortedNameValueList (58), testMapFileReader (64) and TestStringPool (63), for issues that were fixed long ago.

Tests

• testfileutils: TestTFileSystem.TestForceDirRaisesECreateDirFailedIfPathIsRejected is implemented below the TestTFileGenerationHandler_... section header instead of with the other TestTFileSystem methods.
• u_TestTimsort: TestRunsThatBrokeTheOriginalCollapse checks only the sort order, which the broken collapse would get right too; it detects a regression only through the Assert in the TimSort code, so not at all with assertions off. A comment saying so would help.
• _DUnit/DUnitFolderIterator: TFolderTestSuite.ProcessFolder uses EnumFilesOnly / EnumDirsOnly with the default HandleHidden = False, so hidden or system test files and folders are skipped (see [bugs:#74]).

Translations

The merge in r2452 added 4 fuzzy entries each to de and en whose guesses are wrong, e.g. Invalid size %d for TdzBits -> Ungültige Dateiattribute, Bit number %d is out of range 0 .. %d -> Ungültige Ziffer #%d (%s). fr has 100 fuzzy entries. msgfmt ignores fuzzy entries, so they only show up as untranslated, but they should be translated properly or cleared.