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

[J. Ryan Stinnett via llvm-commits]

================
@@ -0,0 +1,170 @@
+# `llvm-debuginfo-analyzer`
+
+These are the notes collected during the development, review and test.
+They describe limitations, known 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.
+
+### 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
----------------
jryans wrote:

```suggestion
In the **comparison functions**, pass references instead of pointers (when
```

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