/// purposes.
///
/// - For static linking: An archive file in this use case contains multiple
-/// normal .obj files and is used for static linking. This is the same
+/// regular .obj files and is used for static linking. This is the same
/// usage as .a file in Unix.
///
/// - For dynamic linking: An archive file in this use case contains pseudo
/// contains a list of DLL names and list of symbols that need to be resolved by
/// the loader. Windows loader maps the executable and all the DLLs to memory,
/// resolves the symbols referencing items in DLLs, and updates the import
-/// address table in memory. The import address table is an array of pointers to
-/// all of the data or functions in DLL referenced by the executable. You cannot
-/// access items in DLLs directly. They have to be accessed through an extra
-/// level of indirection.
+/// address table (IAT) in memory. The IAT is an array of pointers to all of the
+/// data or functions in DLL referenced by the executable. You cannot access
+/// items in DLLs directly. They have to be accessed through an extra level of
+/// indirection.
///
/// So, if you want to access an item in DLL, you have to go through a
-/// pointer. How do you actually do that? For each symbol in DLL, there is
-/// another set of symbols with "_imp__" prefix. For example, if you have a
-/// global variable "foo" in a DLL, a pointer to the variable is exported from
-/// the DLL as "_imp__foo". You cannot directly use "foo" but need to go through
-/// "_imp__foo", because symbol "foo" is not exported.
+/// pointer. How do you actually do that? You need a symbol for a pointer in the
+/// IAT. For each symbol defined in a DLL, a symbol with "__imp_" prefix is
+/// exported from the DLL for an IAT entry. For example, if you have a global
+/// variable "foo" in a DLL, a pointer to the variable is available as
+/// "_imp__foo". The IAT is an array of _imp__ symbols.
///
/// Is this OK? That's not that complicated. Because items in a DLL are not
/// directly accessible, you need to access through a pointer, and the pointer
-/// is available as a symbol with "_imp__" prefix.
+/// is available as a symbol with _imp__ prefix.
///
-/// Trick 1: Although you can write code with "_imp__" prefix, today's compiler
-/// and linker let you write code as if there's no extra level of
-/// indirection. That's why you haven't seen lots of _imp__ in your code. A
-/// variable or a function declared with "dllimport" attributes is treated as an
-/// item in a DLL, and the compiler automatically mangles its name and inserts
-/// the extra level of indirection when accessing the item. Here are some
-/// examples:
+/// Note 1: Although you can write code with _imp__ prefix, today's compiler and
+/// linker let you write code as if there's no extra level of indirection.
+/// That's why you haven't seen lots of _imp__ in your code. A variable or a
+/// function declared with "dllimport" attribute is treated as an item in a DLL,
+/// and the compiler automatically mangles its name and inserts the extra level
+/// of indirection when accessing the item. Here are some examples:
///
/// __declspec(dllimport) int var_in_dll;
-/// var_in_dll = 3; // is equivalent to *_imp__var_in_dll = 3;
+/// var_in_dll = 3; // is equivalent to *_imp__var_in_dll = 3;
///
/// __declspec(dllimport) int fn_in_dll(void);
/// fn_in_dll(); // is equivalent to (*_imp__fn_in_dll)();
/// It's just the compiler rewrites code for you so that you don't need to
/// handle the indirection youself.
///
-/// Trick 2: __declspec(dllimport) is mandatory for data but optional for
+/// Note 2: __declspec(dllimport) is mandatory for data but optional for
/// function. For a function, the linker creates a jump table with the original
-/// symbol name, so that the function is accessible without "_imp__" prefix. The
+/// symbol name, so that the function is accessible without _imp__ prefix. The
/// same function in a DLL can be called through two different symbols if it's
/// not dllimport'ed.
///
/// The above functions do the same thing. fn's content is a JMP instruction to
/// branch to the address pointed by _imp__fn. The latter may be a little bit
/// slower than the former because it will execute the extra JMP instruction, but
-/// that's not an important point here.
+/// that's usually negligible.
///
/// If a function is dllimport'ed, which is usually done in a header file,
/// mangled name will be used at compile time so the jump table will not be
/// used.
///
/// Because there's no way to hide the indirection for data access at link time,
-/// data has to be accessed through dllimport'ed symbols or explicit "_imp__"
+/// data has to be accessed through dllimport'ed symbols or explicit _imp__
/// prefix.
///
/// Creating Atoms for the Import Address Table
/// ===========================================
///
-/// This file is to read a pseudo object file and create at most two atoms. One
-/// is a shared library atom for "_imp__" symbol. The another is a defined atom
-/// for the JMP instruction if the symbol is for a function.
+/// The function in this file reads a pseudo object file and creates at most two
+/// atoms. One is a shared library atom for _imp__ symbol. The another is a
+/// defined atom for the JMP instruction if the symbol is for a function.
///
//===----------------------------------------------------------------------===//