LLD doc tweaks

[thakis]

Summary

• fix minor grammar stuff (I'm not a native speaker either, but it's hopefully a net improvement)
• mention that lld/coff is used in production
• update AArch64, ARM to production quality
• remove lld/include/lld/Core/TODO.txt which looks outdated

[pcc]

lld/docs/index.rst

39 ↗

(On Diff #181288)

Might be worth mentioning that ARM and AArch64 are now being used in production in Chromium?

[ruiu]

LGTM

[smeenai]

lld/docs/index.rst

39 ↗

(On Diff #181288)

Yeah, this entire section seems a bit out of date. x86, x86-64, ARM, and AArch64 all seem well supported now, and they're all at least production quality for us internally.

[thakis]

move aarch64, arm to production quality

[thakis]

lld/docs/index.rst

39 ↗

(On Diff #181288)

Done. I qualified ARM with "(>= v6)" since I think that's what's supported well (?)

lld/trunk/docs/NewLLD.rst

* Speed by design
   Since we are trying to create a high-performance linker,
   it is very important to keep the design as efficient as possible.
 
   Broadly speaking, we do not do anything until we have to do it.
   For example, we do not read section contents or relocations
   until we need them to continue linking.
   When we need to do some costly operation (such as looking up
   a hash table for each symbol), we do it only once.
-  We obtain a handler (which is typically just a pointer to actual data)
+  We obtain a handle (which is typically just a pointer to actual data)
   on the first operation and use it throughout the process.
 
 * Efficient archive file handling
 
   LLD's handling of archive files (the files with ".a" file extension) is
   different from the traditional Unix linkers and similar to Windows linkers.
   We'll describe how the traditional Unix linker handles archive files, what the
   problem is, and how LLD approached the problem.
* Efficient archive file handling
   but that cannot fix the issue of mutually-dependent archive files.
 
   Linking mutually-dependent archive files is tricky.  You may specify the same
   archive file multiple times to let the linker visit it more than once.  Or,
   you may use the special command line options, `--start-group` and
   `--end-group`, to let the linker loop over the files between the options until
   no new symbols are added to the set.
 
-  Visiting the same archive files multiple makes the linker slower.
+  Visiting the same archive files multiple times makes the linker slower.
 
   Here is how LLD approaches the problem. Instead of memorizing only undefined
   symbols, we program LLD so that it memorizes all symbols.  When it sees an
   undefined symbol that can be resolved by extracting an object file from an
-  archive file it previously visited, it immediately extracts the file and link
-  it.  It is doable because LLD does not forget symbols it have seen in archive
+  archive file it previously visited, it immediately extracts the file and links
+  it.  It is doable because LLD does not forget symbols it has seen in archive
   files.
 
-  We believe that the LLD's way is efficient and easy to justify.
+  We believe that LLD's way is efficient and easy to justify.
 
-  The semantics of LLD's archive handling is different from the traditional
+  The semantics of LLD's archive handling are different from the traditional
   Unix's.  You can observe it if you carefully craft archive files to exploit
   it.  However, in reality, we don't know any program that cannot link with our
   algorithm so far, so it's not going to cause trouble.
 
 Numbers You Want to Know
 ------------------------
 
 To give you intuition about what kinds of data the linker is mainly working on,
* Symbol
   There are basically three types of Symbols: Defined, Undefined, or Lazy.
 
   - Defined symbols are for all symbols that are considered as "resolved",
     including real defined symbols, COMDAT symbols, common symbols,
     absolute symbols, linker-created symbols, etc.
   - Undefined symbols represent undefined symbols, which need to be replaced by
     Defined symbols by the resolver until the link is complete.
   - Lazy symbols represent symbols we found in archive file headers
-    which can turn into Defined if we read archieve members.
+    which can turn into Defined if we read archive members.
 
   There's only one Symbol instance for each unique symbol name. This uniqueness
   is guaranteed by the symbol table. As the resolver reads symbols from input
   files, it replaces an existing Symbol with the "best" Symbol for its symbol
   name using the placement new.
 
   The above mechanism allows you to use pointers to Symbols as a very cheap way
   to access name resolution results. Assume for example that you have a pointer

lld/trunk/docs/index.rst

 LLD - The LLVM Linker
 =====================
 
-LLD is a linker from the LLVM project. That is a drop-in replacement
+LLD is a linker from the LLVM project that is a drop-in replacement
 for system linkers and runs much faster than them. It also provides
 features that are useful for toolchain developers.
 
 The linker supports ELF (Unix), PE/COFF (Windows), Mach-O (macOS) and
 WebAssembly in descending order of completeness. Internally, LLD consists of
 several different linkers. The ELF port is the one that will be described in
 this document. The PE/COFF port is complete, including
 Windows debug info (PDB) support. The WebAssembly port is still a work in
 progress (See :doc:`WebAssembly`).  The Mach-O port is built based on a
 different architecture than the others. For the details about Mach-O, please
 read :doc:`AtomLLD`.
 
 Features
 --------
 
-- LLD is a drop-in replacement for the GNU linkers. That accepts the
+- LLD is a drop-in replacement for the GNU linkers that accepts the
   same command line arguments and linker scripts as GNU.
 
   We are currently working closely with the FreeBSD project to make
   LLD default system linker in future versions of the operating
   system, so we are serious about addressing compatibility issues. As
   of February 2017, LLD is able to link the entire FreeBSD/amd64 base
   system including the kernel. With a few work-in-progress patches it
   can link approximately 95% of the ports collection on AMD64. For the
   details, see `FreeBSD quarterly status report
   <https://www.freebsd.org/news/status/report-2016-10-2016-12.html#Using-LLVM%27s-LLD-Linker-as-FreeBSD%27s-System-Linker>`_.
 
 - LLD is very fast. When you link a large program on a multicore
-  machine, you can expect that LLD runs more than twice as fast as GNU
+  machine, you can expect that LLD runs more than twice as fast as the GNU
   gold linker. Your milage may vary, though.
 
 - It supports various CPUs/ABIs including x86-64, x86, x32, AArch64,
   ARM, MIPS 32/64 big/little-endian, PowerPC, PowerPC 64 and AMDGPU.
-  Among these, x86-64 is the most well-supported target and have
-  reached production quality. AArch64 and MIPS seem decent too. x86
-  should be OK but not well tested yet. ARM support is being developed
-  actively.
+  Among these, x86-64, AArch64, and ARM (>= v6) are production quality.
+  MIPS seems decent too. x86 should be OK but is not well tested yet.
 
 - It is always a cross-linker, meaning that it always supports all the
   above targets however it was built. In fact, we don't provide a
   build-time option to enable/disable each target. This should make it
   easy to use our linker as part of a cross-compile toolchain.
 
-- You can embed LLD to your program to eliminate dependency to
+- You can embed LLD in your program to eliminate dependencies on
   external linkers. All you have to do is to construct object files
   and command line arguments just like you would do to invoke an
   external linker and then call the linker's main function,
   ``lld::elf::link``, from your code.
 
 - It is small. We are using LLVM libObject library to read from object
-  files, so it is not completely a fair comparison, but as of February
+  files, so it is not a completely fair comparison, but as of February
   2017, LLD/ELF consists only of 21k lines of C++ code while GNU gold
   consists of 198k lines of C++ code.
 
 - Link-time optimization (LTO) is supported by default. Essentially,
   all you have to do to do LTO is to pass the ``-flto`` option to clang.
   Then clang creates object files not in the native object file format
   but in LLVM bitcode format. LLD reads bitcode object files, compile
   them using LLVM and emit an output file. Because in this way LLD can

 Build
 -----
 
 If you have already checked out LLVM using SVN, you can check out LLD
 under ``tools`` directory just like you probably did for clang. For the
 details, see `Getting Started with the LLVM System
 <http://llvm.org/docs/GettingStarted.html>`_.
 
-If you haven't checkout out LLVM, the easiest way to build LLD is to
-checkout the entire LLVM projects/sub-projects from a git mirror and
+If you haven't checked out LLVM, the easiest way to build LLD is to
+check out the entire LLVM projects/sub-projects from a git mirror and
 build that tree. You need `cmake` and of course a C++ compiler.
 
 .. code-block:: console
 
   $ git clone https://github.com/llvm-project/llvm-project-20170507 llvm-project
   $ mkdir build
   $ cd build
   $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=lld -DCMAKE_INSTALL_PREFIX=/usr/local ../llvm-project/llvm

lld/trunk/docs/open_projects.rst

 .. _open_projects:
 
 Open Projects
 =============
 
-.. include:: ../include/lld/Core/TODO.txt
-
 Documentation TODOs
 ~~~~~~~~~~~~~~~~~~~
 
 .. todolist::

lld/trunk/docs/windows_support.rst

 ===============
 
 LLD supports Windows operating system. When invoked as ``lld-link.exe`` or with
 ``-flavor link``, the driver for Windows operating system is used to parse
 command line options, and it drives further linking processes. LLD accepts
 almost all command line options that the linker shipped with Microsoft Visual
 C++ (link.exe) supports.
 
-The current status is that LLD can link itself on Windows x86/x64
-using Visual C++ 2013 as the compiler.
+The current status is that LLD is used to link production builds of large
+real-world binaries such as Firefox and Chromium.
 
 Development status
 ==================
 
 Driver
   :good:`Mostly done`. Some exotic command line options that are not usually
   used for application develompent, such as ``/DRIVER``, are not supported.
 

lld/trunk/include/lld/Core/TODO.txt

-include/lld/Core
-~~~~~~~~~~~~~~~~
-
-* The yaml reader/writer interfaces should be changed to return
-  an explanatory string if there is an error.  The existing error_code
-  abstraction only works for returning low level OS errors.  It does not
-  work for describing formatting issues.
-
-* We need to add more attributes to File.  In particular, we need cpu
-  and OS information (like target triples).  We should also provide explicit
-  support for `LLVM IR module flags metadata`__.
-
-.. __: http://llvm.org/docs/LangRef.html#module_flags
-.. _Clang: http://clang.llvm.org/docs/InternalsManual.html#Diagnostics