Clean up CCData doxygen docs

Fix typos, remove todos, add details.

Signed-off-by: Younes Manton <ymanton@ca.ibm.com>

compiler/codegen/CCData.hpp

@@ -34,9 +34,21 @@ namespace TR
 /**
  * @class CCData
  *
- * @brief This class represents a table that can be used to implement a GOT or TOC or a PLT or similar.
+ * @brief This class represents a table that can be used to store data that will be referenced from generated code.
  *
- * <TODO: A more detailed discussion about the design here.>
+ * When generating code, we typically have the option to embed constants in the instruction stream in the form of immediate operands, data snippets, and
+ * by allocating chunks of memory directly from the code cache. Alternatively, data can be allocated as static variables accessible via the symbol table.
+ * This class represents a third method for allocating data in a single, contiguous table. Allocations can specify custom alignment requirements and optionally
+ * be associated with a key.
+ *
+ * The intention is for CCData tables to store constants, addresses, and other site-specific data, such as inline caches separately from the instruction stream
+ * itself such that the code can be made read-only (i.e. never needs to be patched), can be made position-independent, and process-independent.
+ *
+ * The memory backing a CCData table must be allocated externally and should be done so to facilitate access from a particular code cache. On architectures that
+ * provide PC-relative data access instructions, the memory should be allocated within the addressible distance of those instructions.
+ *
+ * Alternatively, a register may be used as a base pointer, however note that currently data is allocated from the table at increasing addresses, which may be
+ * sub-optimal for architectures that use signed displacements to access data.
  */
 class CCData
    {
@@ -75,7 +87,13 @@ class CCData
        *
        * Types that don't have any padding or DC bits have unique object representations in C++ standard parlance.
        *
-       * @tparam T The type of the value to create the key from. The type must have a unique object representation. A static assertion checks for the std::has_unique_object_representations<T> type trait on capable compilers.
+       * Guidance
+       *
+       * On capable (C++17) compilers, a static assertion will check for the std::has_unique_object_representations<T> type trait.
+       * On incapable compilers, only simple integrals should be used to create keys. Avoid floats, doubles, structs, classes,
+       * unions, and any other type who's object representation may include undefined bits or bytes.
+       *
+       * @tparam T The type of the value to create the key from. The type must have a unique object representation.
        * @param[In] value The value to create the key from.
        * @return The key.
        */
@@ -93,10 +111,9 @@ class CCData
 
       /**
        * @brief Creates a key_t from the given null-terminated C string.
-
+       *
        * @param[In] data A pointer to the string.
        * @return The key.
-       * \TODO: Decide if we need this; useful for string literals, but susceptible to bugs/attack because of the unbounded string.
        */
       static key_t key(const char * const str);
 
@@ -121,52 +138,53 @@ class CCData
 
       /**
        * @brief Puts the given value in the table, optionally mapped to the given key (if any), aligned to the value's natural type, and returns the index to the value. Synchronized.
-
-       * @tparam T The type of the value to put in the table. The type must be TriviallyCopyable. A static assertion checks for the std::is_trivially_copyable<T> type trait on capable compilers.
+       *
+       * @tparam T The type of the value to put in the table. The type must be TriviallyCopyable, otherwise the runtime behaviour is undefined. A static assertion checks for the std::is_trivially_copyable<T> type trait on capable compilers.
        * @param[In] value The value to put.
        * @param[In] key Optional. The key to map the resulting index to. Without a key the index is the only reference to the data.
        * @param[Out] index The index that refers to the value.
+       * @return True if the value exists in the table, or the key was already mapped to an index, false otherwise.
        */
       template <typename T>
       bool put(const T value, const key_t * const key, index_t &index);
 
       /**
        * @brief Puts the given value in the table, optionally mapped to the given key (if any), aligned to the given boundary (in bytes), and returns the index to the value. Synchronized.
-
+       *
        * @param[In] value Optional. A pointer to the value to put. If null, no data will be copied but the space will be allocated none the less.
        * @param[In] sizeBytes The size of the value pointed to.
        * @param[In] alignmentBytes The alignment (in bytes) to align the value to.
        * @param[In] key Optional. The key to map the resulting index to. Without a key the index is the only reference to the data. If the key is already mapped to an index the operation will return the index and true, but no data will be written.
        * @param[Out] index The index that refers to the value.
-       * @return True if the value was placed in the table, or the key was already mapped to an index, false otherwise.
+       * @return True if the value exists in the table, or the key was already mapped to an index, false otherwise.
        */
       bool put(const uint8_t * const value, const size_t sizeBytes, const size_t alignmentBytes, const key_t * const key, index_t &index);
 
       /**
        * @brief Gets the value referred to by the index from the table.
-
-       * @param[In] T The type of the value to get from the table. The type must be TriviallyCopyable. A static assertion checks for the std::is_trivially_copyable<T> type trait on capable compilers.
+       *
+       * @param[In] T The type of the value to get from the table. The type must be TriviallyCopyable, otherwise the runtime behaviour is undefined. A static assertion checks for the std::is_trivially_copyable<T> type trait on capable compilers.
        * @param[In] index The index that refers to the value.
-       * @param[out] value A reference to the value to write the result to.
-       * @return True if the value was placed in the table, false otherwise.
+       * @param[Out] value A reference to the value to write the result to.
+       * @return True if the value exists in the table, false otherwise.
        */
       template <typename T>
       bool get(const index_t index, T &value) const;
 
       /**
        * @brief Gets the value referred to by the index from the table.
-
+       *
        * @param[In] index The index that refers to the value.
-       * @param[in] value A pointer to the value to write the result to. This parameter is ignored unless this function returns true.
-       * @param[In] sizeBytes The size (in bytes) of the value pointed to. This parameter is ignored unless this function returns true.
+       * @param[Out] value A pointer to the value to write the result to. This parameter is ignored and the value is not changed unless the operation succeeds and this function returns true.
+       * @param[In] sizeBytes The size (in bytes) of the value pointed to. This parameter is ignored unless the operation succeeds and this function returns true.
        * @return True if the index refers to an existing value, false otherwise.
        */
       bool get(const index_t index, uint8_t * const value, const size_t sizeBytes) const;
 
       /**
        * @brief Gets a pointer to the value referred to by the index from the table.
-
-       * @param[In] T The type of the value to get from the table. The type need not be TriviallyCopyable, since this function doesn't do any copying, but it probably should be for symmetry with the put() functions.
+       *
+       * @param[In] T The type of the value to get from the table.
        * @param[In] index The index that refers to the value.
        * @return A pointer to the value if the index refers to an existing value, NULL otherwise.
        */
@@ -175,9 +193,9 @@ class CCData
 
       /**
        * @brief Checks if the given key maps to an index in this table and returns the index. Synchronized.
-
+       *
        * @param[In] key The key to check.
-       * @param[out] index Optional. A pointer to write the index to. This parameter is ignored unless this function returns true.
+       * @param[Out] index Optional. A pointer to write the index to. This parameter is ignored unless this function returns true.
        * @return True if the given key maps to an index, false otherwise.
        */
       bool find(const key_t key, index_t * const index = NULL) const;
@@ -188,7 +206,7 @@ class CCData
        *        This function is NOT synchronized (hence unsafe).
        *
        * @param[In] key The key to check.
-       * @param[out] index Optional. A pointer to write the index to. This parameter is ignored unless this function returns true.
+       * @param[Out] index Optional. A pointer to an index to write to. This parameter is ignored and the index is not changed unless the operation succeeds and this function returns true.
        * @return True if the given key maps to an index, false otherwise.
        */
       bool find_unsafe(const key_t key, index_t * const index = NULL) const;