[mlir][ods] Update doc regarding attribute definitions

[jpienaar]

Thanks!

mlir/docs/OpDefinitions.md

1040

Nit: but with these it seems we are duplicating ourselves, how about just

• DefaultValueAttr: specifies the [default value of an attribute](...).

...

folks can see the link and click if they want to find out more (meaning, I see a link as implicitly meaning "go here to find more info" and so don't need to spell it out).

[antiagainst]

mlir/docs/OpDefinitions.md

1040

Good point. Revised. :)

mlir/docs/OpDefinitions.md

 `CPred` and predicate combiners is preferable since it exposes more information
 (instead hiding all the logic behind a C++ function) into the op definition spec
 so that it can potentially drive more auto-generation cases. But it will
 require a nice library of common predicates as the building blocks to avoid the
 duplication, which is being worked on right now.
 
 ## Attribute Definition
 
+An attribute is a compile-time known constant of an operation.
+
+ODS provides attribute wrappers over C++ attribute classes. There are a few
+common C++ [attribute classes][AttrClasses] defined in MLIR's core IR library
+and one is free to define dialect-specific attribute classes. ODS allows one
+to use these attributes in TableGen to define operations, potentially with
+more fine-grained constraints. For example, `StrAttr` directly maps to
+`StringAttr`; `F32Attr`/`F64Attr` requires the `FloatAttr` to additionally
+be of a certain bitwidth.
+
+ODS attributes are defined as having a storage type (corresponding to a backing
+`mlir::Attribute` that _stores_ the attribute), a return type (corresponding to
+the C++ _return_ type of the generated of the helper getters) as well as method
+to convert between the internal storage and the helper method.
+
+### Attribute decorators
+
+There are a few important attribute adapters/decorators/modifers that can be
+applied to ODS attributes to specify common additional properties like
+optionality, default values, etc.:
+
+*   `DefaultValuedAttr`: specifies the
+    [default value](#attributes-with-default-values) for an attribute.
+*   `OptionalAttr`: specfies an attribute as [optional](#optional-attributes).
+*   `Confined`: adapts an attribute with
+    [further constraints](#confining-attributes).
+
 ### Enum attributes
 
 Some attributes can only take values from an predefined enum, e.g., the
 comparison kind of a comparison op. To define such attributes, ODS provides
 several mechanisms: `StrEnumAttr`, `IntEnumAttr`, and `BitEnumAttr`.
 
 *   `StrEnumAttr`: each enum case is a string, the attribute is stored as a
     [`StringAttr`][StringAttr] in the op.
llvm::Optional<MyBitEnum> symbolizeMyBitEnum(uint32_t value) {
   // Special case for all bits unset.
   if (value == 0) return MyBitEnum::None;
 
   if (value & ~(1u | 2u | 4u)) return llvm::None;
   return static_cast<MyBitEnum>(value);
 }
 ```
 
-TODO(b/132506080): This following is outdated. Update it.
-
-An attribute is a compile time known constant of an operation. Attributes are
-required to be known to construct an operation (e.g., the padding behavior is
-required to fully define the `conv2d` op).
-
-Attributes are defined as having a storage type (corresponding to a derived
-class of `mlir::Attribute`), a return type (that corresponds to the C++ type to
-use in the generation of the helper accessors) as well as method to convert
-between the internal storage and the helper method. Derived attributes are a
-special class of attributes that do not have storage but are instead calculated
-based on the operation and its attributes.
-
 ## Debugging Tips
 
 ### Run `mlir-tblgen` to see the generated content
 
 TableGen syntax sometimes can be obscure; reading the generated content can be
 a very helpful way to understand and debug issues. To build `mlir-tblgen`, run
 `cmake --build . --target mlir-tblgen` in your build directory and find the
 `mlir-tblgen` binary in the `bin/` subdirectory. All the supported generators

 [TableGenIntro]: https://llvm.org/docs/TableGen/LangIntro.html
 [TableGenRef]: https://llvm.org/docs/TableGen/LangRef.html
 [TableGenBackend]: https://llvm.org/docs/TableGen/BackEnds.html#introduction
 [OpBase]: https://github.com/llvm/llvm-project/blob/master/mlir/include/mlir/IR/OpBase.td
 [OpDefinitionsGen]: https://github.com/llvm/llvm-project/blob/master/mlir/tools/mlir-tblgen/OpDefinitionsGen.cpp
 [EnumsGen]: https://github.com/llvm/llvm-project/blob/master/mlir/tools/mlir-tblgen/EnumsGen.cpp
 [StringAttr]: LangRef.md#string-attribute
 [IntegerAttr]: LangRef.md#integer-attribute
+[AttrClasses]: https://github.com/llvm/llvm-project/blob/master/mlir/include/mlir/IR/Attributes.h