[llvm] [llvm-debuginfo-analyzer][DOC] Convert 'README.txt' to markdown. (PR #86394)

[J. Ryan Stinnett via llvm-commits]

================
@@ -0,0 +1,171 @@
+# llvm-debuginfo-analyzer
+
+These are the notes collected during the development, review and test.
+They describe limitations, know issues and future work.
+
+### Remove the use of macros in *LVReader.h* that describe the *bumpallocators*.
+**[D137933](https://reviews.llvm.org/D137933#inline-1389904)**
+
+Use a standard (or LLVM) **map** with **typeinfo** (would need a specialization
+to expose equality and hasher) for the allocators and the creation
+functions could be a function template.
+
+.. _lit-test-label:
+### Use a *lit test* instead of a *unit test* for the *logical readers*.
+**[D125783](https://reviews.llvm.org/D125783#inline-1324376)**
+
+As the **DebugInfoLogicalView** library is sufficiently exposed via the
+**llvm-debuginfo-analyzer** tool, follow the LLVM general approach and
+use **LIT** tests to validate the **logical readers**.
+
+Convert the **unitests**:
+```
+llvm-project/llvm/unittests/DebugInfo/LogicalView/CodeViewReaderTest.cpp
+llvm-project/llvm/unittests/DebugInfo/LogicalView/DWARFReaderTest.cpp
+```
+into **LIT tests**:
+```
+llvm-project/llvm/test/DebugInfo/LogicalView/CodeViewReader.test
+llvm-project/llvm/test/DebugInfo/LogicalView/DWARFReader.test
+```
+
+### Eliminate calls to *getInputFileDirectory()* in the unit tests.
+**[D125783](https://reviews.llvm.org/D125783#inline-1324359)**
+
+Rewrite the unittests **ReaderTest** and **CodeViewReaderTest** to eliminate
+the call:
+```
+  getInputFileDirectory()
+```
+as use of that call is discouraged.
+
+### Fix mismatch between *%d/%x* format strings and *uint64_t* type.
+**[D137400](https://reviews.llvm.org/D137400) / [58758](https://github.com/llvm/llvm-project/issues/58758)**
+
+Incorrect printing of **uint64_t** on **32-bit** platforms.
+Add the **PRIx64** specifier to the printing code (**format()**).
+
+### Remove *LVScope::Children* container.
+**[D137933](https://reviews.llvm.org/D137933#inline-1373902)**
+
+Use a **chaining iterator** over the other containers rather than keep a
+separate container **Children** that mirrors their contents.
+
+### Use *TableGen* for command line options.
+**[D125777](https://reviews.llvm.org/D125777#inline-1291801)**
+
+The current trend is to use **TableGen** for command-line options in tools.
+Change command line options to use **tablegen** as many other LLVM tools.
+
+### *LVDoubleMap* to return *optional\<ValueType\>* instead of null pointer.
+**[D125783](https://reviews.llvm.org/D125783#inline-1294164)**
+
+The more idiomatic LLVM way to handle this would be to have **find**
+return **Optional\<ValueType\>**.
+
+### Pass references instead of pointers (*Comparison functions*).
+**[D125782](https://reviews.llvm.org/D125782#inline-1293920)**
+
+In the **comparison functions**, pass references instead of pointers (when
+pointers cannot be null).
+
+### Use *StringMap* where possible.
+**[D125783](https://reviews.llvm.org/D125783#inline-1294211)**
+
+LLVM has a **StringMap** class that is advertised as more efficient than
+**std::map\<std::string, ValueType\>**. Mainly it does fewer allocations
+because the key is not a **std::string**.
+
+Replace the use of **std::map\<std::string, ValueType\>** with **StringMap**.
+One specific case is the **LVSymbolNames** definitions.
+
+### Calculate unique offset for *CodeView* elements.
+In order to have the same logical functionality as the **DWARF Reader**, such
----------------
jryans wrote:

```suggestion
In order to have the same logical functionality as the **DWARF reader**, such
```

https://github.com/llvm/llvm-project/pull/86394