doc: backends: Add Doxygen-style documentation for BMV2 JSONObjects

1. Class Overview:
   - Provides an overview of the JsonObjects class, explaining its purpose and namespace.

2. Constructor:
   - Documented the constructor `JsonObjects::JsonObjects()` with a brief description of its purpose and initialization of member variables.

3. Member Functions:
   - Each member function of the JsonObjects class is documented with detailed descriptions.

   - Special attention is given to functions with complex logic or multiple parameters to ensure detailed documentation.

Overall, this commit enhances the understanding of the BMV2 JSON Objects class by providing a Doxygen-style documentation.

backends/bmv2/common/JsonObjects.cpp

@@ -19,11 +19,20 @@ limitations under the License.
 #include "helpers.h"
 #include "lib/json.h"
 
+/**
+ * @file JsonObjects.h
+ *
+ * @brief Declaration of the JsonObjects class.
+ */
 namespace BMV2 {
 
 const int JSON_MAJOR_VERSION = 2;
 const int JSON_MINOR_VERSION = 23;
 
+/**
+ * @brief Constructs a new JsonObjects instance.
+ * Initializes the top-level JsonObject and other member arrays.
+ */
 JsonObjects::JsonObjects() {
     toplevel = new Util::JsonObject();
     meta = new Util::JsonObject();
@@ -52,6 +61,11 @@ JsonObjects::JsonObjects() {
     field_aliases = insert_array_field(toplevel, "field_aliases");
 }
 
+/**
+ * @brief Retrieves the contents of a field list identified by its ID.
+ * @param id The ID of the field list.
+ * @return A pointer to the JsonArray containing the field list's elements, or nullptr if not found.
+ */
 Util::JsonArray *JsonObjects::get_field_list_contents(unsigned id) const {
     for (auto e : *field_lists) {
         auto obj = e->to<Util::JsonObject>();
@@ -63,6 +77,12 @@ Util::JsonArray *JsonObjects::get_field_list_contents(unsigned id) const {
     return nullptr;
 }
 
+/**
+ * @brief Finds an object in a JSON array by its name.
+ * @param array The JSON array to search in.
+ * @param name The name of the object to find.
+ * @return A pointer to the JsonObject with the specified name, or nullptr if not found.
+ */
 Util::JsonObject *JsonObjects::find_object_by_name(Util::JsonArray *array, const cstring &name) {
     for (auto e : *array) {
         auto obj = e->to<Util::JsonObject>();
@@ -74,27 +94,45 @@ Util::JsonObject *JsonObjects::find_object_by_name(Util::JsonArray *array, const
     return nullptr;
 }
 
-/// Insert a json array to a parent object under key 'name'.
+/**
+ * @brief Inserts a JSON array into a parent object under a specified key.
+ * @param parent The parent JsonObject to insert the array into.
+ * @param name The key under which the array will be inserted.
+ * @return A pointer to the newly created JSON array.
+ */
 Util::JsonArray *JsonObjects::insert_array_field(Util::JsonObject *parent, cstring name) {
     auto result = new Util::JsonArray();
     parent->emplace(name, result);
     return result;
 }
 
-/// Append a json array to a parent json array.
+/**
+ * @brief Appends a JSON array to a parent JSON array.
+ * @param parent The parent JsonArray to which the array will be appended.
+ * @return A pointer to the newly created JSON array.
+ */
 Util::JsonArray *JsonObjects::append_array(Util::JsonArray *parent) {
     auto result = new Util::JsonArray();
     parent->append(result);
     return result;
 }
 
-/// Insert a json array named 'parameters' in a parent json object.
+/**
+ * @brief Creates a JSON array named 'parameters' in a parent JsonObject.
+ * @param object The parent JsonObject in which the 'parameters' array will be created.
+ * @return A pointer to the newly created JSON array.
+ */
 Util::JsonArray *JsonObjects::create_parameters(Util::JsonObject *object) {
     return insert_array_field(object, "parameters");
 }
 
+/**
+ * @brief Adds program information to the top-level JsonObject.
+ * @param name The name of the program.
+ */
 void JsonObjects::add_program_info(const cstring &name) { toplevel->emplace("program", name); }
 
+///@brief Adds meta information to the JsonObject.
 void JsonObjects::add_meta_info() {
     static constexpr int version_major = JSON_MAJOR_VERSION;
     static constexpr int version_minor = JSON_MINOR_VERSION;
@@ -106,12 +144,13 @@ void JsonObjects::add_meta_info() {
 }
 
 /**
- * Create a header type in json.
+ * @brief Create a header type in json.
  * @param name header name
  * @param type header type
  * @param max_length  maximum length for a header with varbit fields;
  *                    if 0 header does not contain varbit fields
  * @param fields a JsonArray for the fields in the header
+ * @return The ID of the newly created header type.
  */
 unsigned JsonObjects::add_header_type(const cstring &name, Util::JsonArray *&fields,
                                       unsigned max_length) {
@@ -136,6 +175,12 @@ unsigned JsonObjects::add_header_type(const cstring &name, Util::JsonArray *&fie
     return id;
 }
 
+/**
+ * @brief Creates a union type in JSON.
+ * @param name The name of the union type.
+ * @param fields A JsonArray containing the headers in the union type.
+ * @return The ID of the newly created union type.
+ */
 unsigned JsonObjects::add_union_type(const cstring &name, Util::JsonArray *&fields) {
     std::string sname(name, name.size());
     auto it = union_type_id.find(sname);
@@ -155,7 +200,11 @@ unsigned JsonObjects::add_union_type(const cstring &name, Util::JsonArray *&fiel
     return id;
 }
 
-/// Create a header type with empty field list.
+/**
+ * @brief Creates a header type in JSON with an empty field list.
+ * @param name The name of the header type.
+ * @return The ID of the newly created header type.
+ */
 unsigned JsonObjects::add_header_type(const cstring &name) {
     std::string sname(name, name.size());
     auto header_type_id_it = header_type_id.find(sname);
@@ -173,8 +222,11 @@ unsigned JsonObjects::add_header_type(const cstring &name) {
     return id;
 }
 
-/// Create a set of fields to an existing header type.
-/// The header type is decribed by the name.
+/**
+ * @brief Adds a set of fields to an existing header type.
+ * @param name The name of the header type.
+ * @param field The JsonArray containing the fields to add.
+ */
 void JsonObjects::add_header_field(const cstring &name, Util::JsonArray *&field) {
     CHECK_NULL(field);
     Util::JsonObject *headerType = find_object_by_name(header_types, name);
@@ -183,7 +235,12 @@ void JsonObjects::add_header_field(const cstring &name, Util::JsonArray *&field)
     fields->append(field);
 }
 
-/// Create a header instance in json.
+/**
+ * @brief Creates a header instance in JSON.
+ * @param type The type of the header.
+ * @param name The name of the header instance.
+ * @return The ID of the newly created header instance.
+ */
 unsigned JsonObjects::add_header(const cstring &type, const cstring &name) {
     auto header = new Util::JsonObject();
     unsigned id = BMV2::nextId("headers");
@@ -197,7 +254,13 @@ unsigned JsonObjects::add_header(const cstring &type, const cstring &name) {
     return id;
 }
 
-/// Create a header_union instance in json.
+/**
+ * @brief Creates a header union instance in JSON.
+ * @param type The type of the header union.
+ * @param headers A JsonArray containing the header IDs in the union.
+ * @param name The name of the header union instance.
+ * @return The ID of the newly created header union instance.
+ */
 unsigned JsonObjects::add_union(const cstring &type, Util::JsonArray *&headers,
                                 const cstring &name) {
     auto u = new Util::JsonObject();
@@ -212,6 +275,12 @@ unsigned JsonObjects::add_union(const cstring &type, Util::JsonArray *&headers,
     return id;
 }
 
+/**
+ * @brief Creates a metadata header instance in JSON.
+ * @param type The type of the metadata.
+ * @param name The name of the metadata header instance.
+ * @return The ID of the newly created metadata header instance.
+ */
 unsigned JsonObjects::add_metadata(const cstring &type, const cstring &name) {
     auto header = new Util::JsonObject();
     unsigned id = BMV2::nextId("headers");
@@ -225,6 +294,13 @@ unsigned JsonObjects::add_metadata(const cstring &type, const cstring &name) {
     return id;
 }
 
+/**
+ * @brief Adds a header stack to the JSON representation.
+ * @param type The type of the headers in the stack.
+ * @param name The name of the header stack.
+ * @param size The size of the header stack.
+ * @param ids The vector of header IDs in the stack.
+ */
 void JsonObjects::add_header_stack(const cstring &type, const cstring &name, const unsigned size,
                                    const std::vector<unsigned> &ids) {
     auto stack = new Util::JsonObject();
@@ -241,6 +317,13 @@ void JsonObjects::add_header_stack(const cstring &type, const cstring &name, con
     header_stacks->append(stack);
 }
 
+/**
+ * @brief Adds a header union stack to the JSON representation.
+ * @param type The type of the header unions in the stack.
+ * @param name The name of the header union stack.
+ * @param size The size of the header union stack.
+ * @param ids The vector of header union IDs in the stack.
+ */
 void JsonObjects::add_header_union_stack(const cstring &type, const cstring &name,
                                          const unsigned size, const std::vector<unsigned> &ids) {
     auto stack = new Util::JsonObject();
@@ -257,15 +340,23 @@ void JsonObjects::add_header_union_stack(const cstring &type, const cstring &nam
     header_union_stacks->append(stack);
 }
 
-/// Add an error to json.
+/**
+ * @brief Adds an error to the JSON representation.
+ * @param name The name of the error.
+ * @param type The type of the error.
+ */
 void JsonObjects::add_error(const cstring &name, const unsigned type) {
     auto arr = append_array(errors);
     arr->append(name);
     arr->append(type);
 }
 
-/// Add a single enum entry to json.
-/// A enum entry is identified with { enum_name, entry_name, entry_value }
+/**
+ * @brief Adds a single enum entry to the JSON representation.
+ * @param enum_name The name of the enum.
+ * @param entry_name The name of the enum entry.
+ * @param entry_value The value of the enum entry.
+ */
 void JsonObjects::add_enum(const cstring &enum_name, const cstring &entry_name,
                            const unsigned entry_value) {
     // look up enum in json by name
@@ -290,6 +381,11 @@ void JsonObjects::add_enum(const cstring &enum_name, const cstring &entry_name,
     }
 }
 
+/**
+ * @brief Adds a parser to the JSON representation.
+ * @param name The name of the parser.
+ * @return The ID of the newly created parser.
+ */
 unsigned JsonObjects::add_parser(const cstring &name) {
     auto parser = new Util::JsonObject();
     unsigned id = BMV2::nextId("parser");
@@ -304,8 +400,12 @@ unsigned JsonObjects::add_parser(const cstring &name) {
     return id;
 }
 
-/// insert parser state into a parser identified by parser_id
-/// return the id of the parser state
+/**
+ * @brief Adds a parser state to an existing parser in the JSON representation.
+ * @param parser_id The ID of the parser.
+ * @param state_name The name of the parser state.
+ * @return The ID of the newly created parser state.
+ */
 unsigned JsonObjects::add_parser_state(const unsigned parser_id, const cstring &state_name) {
     if (map_parser.find(parser_id) == map_parser.end()) BUG("parser %1% not found.", parser_id);
     auto parser = map_parser[parser_id];
@@ -326,6 +426,11 @@ unsigned JsonObjects::add_parser_state(const unsigned parser_id, const cstring &
     return state_id;
 }
 
+/**
+ * @brief Adds a parser transition to an existing parser state in the JSON representation.
+ * @param state_id The ID of the parser state.
+ * @param transition The transition to add.
+ */
 void JsonObjects::add_parser_transition(const unsigned state_id, Util::IJson *transition) {
     if (map_parser_state.find(state_id) == map_parser_state.end())
         BUG("parser state %1% not found.", state_id);
@@ -337,6 +442,11 @@ void JsonObjects::add_parser_transition(const unsigned state_id, Util::IJson *tr
     transitions->append(trans);
 }
 
+/**
+ * @brief Adds a parser operation to an existing parser state in the JSON representation.
+ * @param state_id The ID of the parser state.
+ * @param op The operation to add.
+ */
 void JsonObjects::add_parser_op(const unsigned state_id, Util::IJson *op) {
     if (map_parser_state.find(state_id) == map_parser_state.end())
         BUG("parser state %1% not found.", state_id);
@@ -346,6 +456,11 @@ void JsonObjects::add_parser_op(const unsigned state_id, Util::IJson *op) {
     statements->append(op);
 }
 
+/**
+ * @brief Adds a parser transition key to an existing parser state in the JSON representation.
+ * @param state_id The ID of the parser state.
+ * @param newKey The new transition key to add.
+ */
 void JsonObjects::add_parser_transition_key(const unsigned state_id, Util::IJson *newKey) {
     if (map_parser_state.find(state_id) != map_parser_state.end()) {
         auto state = map_parser_state[state_id];
@@ -358,6 +473,12 @@ void JsonObjects::add_parser_transition_key(const unsigned state_id, Util::IJson
     }
 }
 
+/**
+ * @brief Adds a parse vset to the JSON representation.
+ * @param name The name of the parse vset.
+ * @param bitwidth The compressed bit width of the parse vset.
+ * @param size The maximum size of the parse vset.
+ */
 void JsonObjects::add_parse_vset(const cstring &name, const unsigned bitwidth,
                                  const big_int &size) {
     auto parse_vset = new Util::JsonObject();
@@ -369,6 +490,13 @@ void JsonObjects::add_parse_vset(const cstring &name, const unsigned bitwidth,
     parse_vsets->append(parse_vset);
 }
 
+/**
+ * @brief Adds an action to the JSON representation.
+ * @param name The name of the action.
+ * @param params The runtime data parameters of the action.
+ * @param body The primitives body of the action.
+ * @return The ID of the newly created action.
+ */
 unsigned JsonObjects::add_action(const cstring &name, Util::JsonArray *&params,
                                  Util::JsonArray *&body) {
     CHECK_NULL(params);
@@ -383,6 +511,13 @@ unsigned JsonObjects::add_action(const cstring &name, Util::JsonArray *&params,
     return id;
 }
 
+/**
+ * @brief Adds an extern attribute to the JSON representation.
+ * @param name The name of the attribute.
+ * @param type The type of the attribute.
+ * @param value The value of the attribute.
+ * @param attributes The attributes array to add the new attribute to.
+ */
 void JsonObjects::add_extern_attribute(const cstring &name, const cstring &type,
                                        const cstring &value, Util::JsonArray *attributes) {
     auto attr = new Util::JsonObject();
@@ -392,6 +527,12 @@ void JsonObjects::add_extern_attribute(const cstring &name, const cstring &type,
     attributes->append(attr);
 }
 
+/**
+ * @brief Adds an extern instance to the JSON representation.
+ * @param name The name of the extern instance.
+ * @param type The type of the extern instance.
+ * @param attributes The attributes array of the extern instance.
+ */
 void JsonObjects::add_extern(const cstring &name, const cstring &type,
                              Util::JsonArray *attributes) {
     auto extn = new Util::JsonObject();