Documentation: HowToUseAttributes: formatting (use monospaced font)

llvm-svn: 174982

Author: gribozavr

llvm/docs/HowToUseAttributes.rst

@@ -1,80 +1,81 @@
-==============================================
+=====================
 How To Use Attributes
-==============================================
+=====================
 
 .. contents::
-   :local:
+  :local:
 
 Introduction
 ============
 
-Attributes in LLVM have changed in some fundamental ways. It was necessary to do
-this to support expanding the attributes to encompass more than a handful of
-attributes --- e.g. command line options. The old way of handling attributes
-consisted of representing them as a bit mask of values. This bit mask was stored
-in a "list" structure that was reference counted. The advantage of this was that
-attributes could be manipulated with 'or's and 'and's. The disadvantage of this
-was that there was limited room for expansion, and virtually no support for
-attribute-value pairs other than alignment.
-
-In the new scheme, an Attribute object represents a single attribute that's
-uniqued. You use the "Attribute::get" methods to create a new Attribute
-object. An attribute can be a single "enum" value (the enum being the
-Attribute::AttrKind enum), a string representing a target-dependent attribute,
-or an attribute-value pair. Some examples:
-
-* Target-independent:   noinline, zext
-* Target-dependent:     "no-sse", "thumb2"
-* Attribute-value pair: "cpu" = "cortex-a8", align = 4
+Attributes in LLVM have changed in some fundamental ways.  It was necessary to
+do this to support expanding the attributes to encompass more than a handful of
+attributes --- e.g. command line options.  The old way of handling attributes
+consisted of representing them as a bit mask of values.  This bit mask was
+stored in a "list" structure that was reference counted.  The advantage of this
+was that attributes could be manipulated with 'or's and 'and's.  The
+disadvantage of this was that there was limited room for expansion, and
+virtually no support for attribute-value pairs other than alignment.
+
+In the new scheme, an ``Attribute`` object represents a single attribute that's
+uniqued.  You use the ``Attribute::get`` methods to create a new ``Attribute``
+object.  An attribute can be a single "enum" value (the enum being the
+``Attribute::AttrKind`` enum), a string representing a target-dependent
+attribute, or an attribute-value pair.  Some examples:
+
+* Target-independent: ``noinline``, ``zext``
+* Target-dependent: ``"no-sse"``, ``"thumb2"``
+* Attribute-value pair: ``"cpu" = "cortex-a8"``, ``align = 4``
 
 Note: for an attribute value pair, we expect a target-dependent attribute to
 have a string for the value.
 
-Attribute
-=========
-An Attribute object is designed to be passed around by value.
+``Attribute``
+=============
+An ``Attribute`` object is designed to be passed around by value.
 
 Because attributes are no longer represented as a bit mask, you will need to
 convert any code which does treat them as a bit mask to use the new query
 methods on the Attribute class.
 
-AttributeSet
-============
+``AttributeSet``
+================
 
-The next class is the AttributeSet class. This replaces the old AttributeList
-class. The AttributeSet stores a collection of Attribute objects for each kind
-of object that may have an attribute associated with it: the function as a
-whole, the return type, or the function's parameters. A function's attributes
-are at index "AttributeSet::FunctionIndex"; the return type's attributes are at
-index "AttributeSet::ReturnIndex"; and the function's parameters' attributes are
-at indices 1, ..., n (where 'n' is the number of parameters). Most methods on
-the AttributeSet class take an index parameter.
+The ``AttributeSet`` class replaces the old ``AttributeList`` class.  The
+``AttributeSet`` stores a collection of Attribute objects for each kind of
+object that may have an attribute associated with it: the function as a
+whole, the return type, or the function's parameters.  A function's attributes
+are at index ``AttributeSet::FunctionIndex``; the return type's attributes are
+at index ``AttributeSet::ReturnIndex``; and the function's parameters'
+attributes are at indices 1, ..., n (where 'n' is the number of parameters).
+Most methods on the ``AttributeSet`` class take an index parameter.
 
-An AttributeSet is also a uniqued and immutable object. You create an
-AttributeSet through the "AttributeSet::get" methods. You can add and remove
-attributes, which result in the creation of a new AttributeSet.
+An ``AttributeSet`` is also a uniqued and immutable object.  You create an
+``AttributeSet`` through the ``AttributeSet::get`` methods.  You can add and
+remove attributes, which result in the creation of a new ``AttributeSet``.
 
-An AttributeSet object is designed to be passed around by value.
+An ``AttributeSet`` object is designed to be passed around by value.
 
-Note: It is advised that you do *not* use the AttributeSet "Introspection"
-methods (e.g. 'Raw', 'getRawPointer', etc.). These methods break encapsulation,
-and may be removed in a future release (i.e. 4.0).
+Note: It is advised that you do *not* use the ``AttributeSet`` "introspection"
+methods (e.g. ``Raw``, ``getRawPointer``, etc.).  These methods break
+encapsulation, and may be removed in a future release (i.e. LLVM 4.0).
 
-AttrBuilder
-================
+``AttrBuilder``
+===============
 
-Lastly, we have a 'builder' class to help create the AttributeSet object without
-having to create several different intermediate uniqued AttributeSet
-objects. The AttrBuilder class allows you to add and remove attributes at
-will. The attributes won't be uniqued until you call the appropriate
-"AttributeSet::get" method.
+Lastly, we have a "builder" class to help create the ``AttributeSet`` object
+without having to create several different intermediate uniqued
+``AttributeSet`` objects.  The ``AttrBuilder`` class allows you to add and
+remove attributes at will.  The attributes won't be uniqued until you call the
+appropriate ``AttributeSet::get`` method.
 
-An AttrBuilder object is *not* designed to be passed around by value. It should
-be passed by reference.
+An ``AttrBuilder`` object is *not* designed to be passed around by value.  It
+should be passed by reference.
 
-Note: It is advised that you do *not* use the "AttrBuilder::addRawValue()"
-method or the "AttrBuilder(uint64_t Val)" c'tor. These are for backwards
-compatibility and may be removed in a future release (i.e. 4.0).
+Note: It is advised that you do *not* use the ``AttrBuilder::addRawValue()``
+method or the ``AttrBuilder(uint64_t Val)`` constructor.  These are for
+backwards compatibility and may be removed in a future release (i.e. LLVM 4.0).
 
 And that's basically it! A lot of functionality is hidden behind these classes,
 but the interfaces are pretty straight forward.
+