[Doc] Fix getelementptr description about arguments

[chenwj]

Summary

Section "Arguments" of getelementptr [1] says the first argument is a type, the second argument is a pointer or a vector of pointers, and is the base address to start from. Update getelementptr FAQ [2] accordingly, based on discussion with David on the mailing list [3].

[1] http://llvm.org/docs/LangRef.html#getelementptr-instruction
[2] http://llvm.org/docs/GetElementPtr.html
[3] http://lists.llvm.org/pipermail/llvm-dev/2017-June/114294.html

[dblaikie]

Thanks - commit when ready. If you don't have commit access, reply here & I'll commit it for you.

docs/GetElementPtr.rst

 it to known concepts from other programming paradigms, most notably C array
 indexing and field selection. GEP closely resembles C array indexing and field
 selection, however it is a little different and this leads to the following
 questions.
 
 What is the first index of the GEP instruction?
 -----------------------------------------------
 
-Quick answer: The index stepping through the first operand.
+Quick answer: The index stepping through the second operand.
 
 The confusion with the first index usually arises from thinking about the
 GetElementPtr instruction as if it was a C index operator. They aren't the
 same. For example, when we write, in "C":
 
 .. code-block:: c++
 
   AType *Foo;

 Sometimes this question gets rephrased as:
 
 .. _GEP index through first pointer:
 
   *Why is it okay to index through the first pointer, but subsequent pointers
   won't be dereferenced?*
 
 The answer is simply because memory does not have to be accessed to perform the
-computation. The first operand to the GEP instruction must be a value of a
+computation. The second operand to the GEP instruction must be a value of a
 pointer type. The value of the pointer is provided directly to the GEP
 instruction as an operand without any need for accessing memory. It must,
 therefore be indexed and requires an index operand. Consider this example:
 
 .. code-block:: c++
 
   struct munger_struct {
     int f1;
     int f2;
   };
   void munge(struct munger_struct *P) {
     P[0].f1 = P[1].f1 + P[2].f2;
   }
   ...
   munger_struct Array[3];
   ...
   munge(Array);
 
 In this "C" example, the front end compiler (Clang) will generate three GEP
 instructions for the three indices through "P" in the assignment statement.  The
-function argument ``P`` will be the first operand of each of these GEP
-instructions.  The second operand indexes through that pointer.  The third
+function argument ``P`` will be the second operand of each of these GEP
+instructions.  The third operand indexes through that pointer.  The fourth
 operand will be the field offset into the ``struct munger_struct`` type, for
 either the ``f1`` or ``f2`` field. So, in LLVM assembly the ``munge`` function
 looks like:
 
 .. code-block:: llvm
 
   void %munge(%struct.munger_struct* %P) {
   entry:
     %tmp = getelementptr %struct.munger_struct, %struct.munger_struct* %P, i32 1, i32 0
     %tmp = load i32* %tmp
     %tmp6 = getelementptr %struct.munger_struct, %struct.munger_struct* %P, i32 2, i32 1
     %tmp7 = load i32* %tmp6
     %tmp8 = add i32 %tmp7, %tmp
     %tmp9 = getelementptr %struct.munger_struct, %struct.munger_struct* %P, i32 0, i32 0
     store i32 %tmp8, i32* %tmp9
     ret void
   }
 
-In each case the first operand is the pointer through which the GEP instruction
-starts. The same is true whether the first operand is an argument, allocated
+In each case the second operand is the pointer through which the GEP instruction
+starts. The same is true whether the second operand is an argument, allocated
 memory, or a global variable.
 
 To make this clear, let's consider a more obtuse example:
 
 .. code-block:: text
 
   %MyVar = uninitialized global i32
   ...

 0`` index is needed. However, a closer inspection of how globals and GEPs work
 reveals the need. Becoming aware of the following facts will dispel the
 confusion:
 
 #. The type of ``%MyStruct`` is *not* ``{ float*, i32 }`` but rather ``{ float*,
    i32 }*``. That is, ``%MyStruct`` is a pointer to a structure containing a
    pointer to a ``float`` and an ``i32``.
 
-#. Point #1 is evidenced by noticing the type of the first operand of the GEP
+#. Point #1 is evidenced by noticing the type of the second operand of the GEP
    instruction (``%MyStruct``) which is ``{ float*, i32 }*``.
 
 #. The first index, ``i64 0`` is required to step over the global variable
-   ``%MyStruct``.  Since the first argument to the GEP instruction must always
+   ``%MyStruct``.  Since the second argument to the GEP instruction must always
    be a value of pointer type, the first index steps through that pointer. A
    value of 0 means 0 elements offset from that pointer.
 
 #. The second index, ``i32 1`` selects the second field of the structure (the
    ``i32``).
 
 What is dereferenced by GEP?
 ----------------------------

 
 This hasn't always been forcefully disallowed, though it's not recommended.  It
 leads to awkward special cases in the optimizers, and fundamental inconsistency
 in the IR. In the future, it will probably be outright disallowed.
 
 What effect do address spaces have on GEPs?
 -------------------------------------------
 
-None, except that the address space qualifier on the first operand pointer type
+None, except that the address space qualifier on the second operand pointer type
 always matches the address space qualifier on the result type.
 
 How is GEP different from ``ptrtoint``, arithmetic, and ``inttoptr``?
 ---------------------------------------------------------------------
 
 It's very similar; there are only subtle differences.
 
 With ptrtoint, you have to pick an integer type. One approach is to pick i64;

 
 In summary, here's some things to always remember about the GetElementPtr
 instruction:
 
 
 #. The GEP instruction never accesses memory, it only provides pointer
    computations.
 
-#. The first operand to the GEP instruction is always a pointer and it must be
+#. The second operand to the GEP instruction is always a pointer and it must be
    indexed.
 
 #. There are no superfluous indices for the GEP instruction.
 
 #. Trailing zero indices are superfluous for pointer aliasing, but not for the
    types of the pointers.
 
 #. Leading zero indices are not superfluous for pointer aliasing nor the types
    of the pointers.

docs/LangRef.rst

-  An integer constant other than zero or a pointer value returned from
    ranges allocated through mechanisms other than those provided by
    LLVM. Such ranges shall not overlap with any ranges of addresses
    allocated by mechanisms provided by LLVM.
 
 A pointer value is *based* on another pointer value according to the
 following rules:
 
 -  A pointer value formed from a ``getelementptr`` operation is *based*
-   on the first value operand of the ``getelementptr``.
+   on the second value operand of the ``getelementptr``.
 -  The result value of a ``bitcast`` is *based* on the operand of the
    ``bitcast``.
 -  A pointer value formed by an ``inttoptr`` is *based* on all pointer
    values that contribute (directly or indirectly) to the computation of
    the pointer's value.
 -  The "*based* on" relationship is transitive.
 
 Note that this definition of *"based"* is intentionally similar to the
``bitcast (CST to TYPE)``
     instruction <i_bitcast>`.
 ``addrspacecast (CST to TYPE)``
     Convert a constant pointer or constant vector of pointer, CST, to another
     TYPE in a different address space. The constraints of the operands are the
     same as those for the :ref:`addrspacecast instruction <i_addrspacecast>`.
 ``getelementptr (TY, CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (TY, CSTPTR, IDX0, IDX1, ...)``
     Perform the :ref:`getelementptr operation <i_getelementptr>` on
     constants. As with the :ref:`getelementptr <i_getelementptr>`
-    instruction, the index list may have zero or more indexes, which are
+    instruction, the index list may have one or more indexes, which are
     required to make sense for the type of "pointer to TY".
 ``select (COND, VAL1, VAL2)``
     Perform the :ref:`select operation <i_select>` on constants.
 ``icmp COND (VAL1, VAL2)``
     Performs the :ref:`icmp operation <i_icmp>` on constants.
 ``fcmp COND (VAL1, VAL2)``
     Performs the :ref:`fcmp operation <i_fcmp>` on constants.
 ``extractelement (VAL, IDX)``

 """"""""""
 
 The first argument is always a type used as the basis for the calculations.
 The second argument is always a pointer or a vector of pointers, and is the
 base address to start from. The remaining arguments are indices
 that indicate which of the elements of the aggregate object are indexed.
 The interpretation of each index is dependent on the type being indexed
 into. The first index always indexes the pointer value given as the
-first argument, the second index indexes a value of the type pointed to
+second argument, the second index indexes a value of the type pointed to
 (not necessarily the value directly pointed to, since the first index
 can be non-zero), etc. The first type indexed into must be a pointer
 value, subsequent types can be arrays, vectors, and structs. Note that
 subsequent types being indexed into can never be pointers, since that
 would require loading the pointer before continuing calculation.
 
 The type of each index argument depends on the type it is indexing into.
 When indexing into a (optionally packed) structure, only ``i32`` integer