[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

@@ -74,21 +74,18 @@ Util::JsonObject *JsonObjects::find_object_by_name(Util::JsonArray *array, const
     return nullptr;
 }
 
-/// Insert a json array to a parent object under key 'name'.
 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.
 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.
 Util::JsonArray *JsonObjects::create_parameters(Util::JsonObject *object) {
     return insert_array_field(object, "parameters");
 }
@@ -105,14 +102,6 @@ void JsonObjects::add_meta_info() {
     toplevel->emplace("__meta__", meta);
 }
 
-/**
- * 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
- */
 unsigned JsonObjects::add_header_type(const cstring &name, Util::JsonArray *&fields,
                                       unsigned max_length) {
     std::string sname(name, name.size());
@@ -155,7 +144,6 @@ unsigned JsonObjects::add_union_type(const cstring &name, Util::JsonArray *&fiel
     return id;
 }
 
-/// Create a header type with empty field list.
 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 +161,6 @@ 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.
 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 +169,6 @@ void JsonObjects::add_header_field(const cstring &name, Util::JsonArray *&field)
     fields->append(field);
 }
 
-/// Create a header instance in json.
 unsigned JsonObjects::add_header(const cstring &type, const cstring &name) {
     auto header = new Util::JsonObject();
     unsigned id = BMV2::nextId("headers");
@@ -197,7 +182,6 @@ unsigned JsonObjects::add_header(const cstring &type, const cstring &name) {
     return id;
 }
 
-/// Create a header_union instance in json.
 unsigned JsonObjects::add_union(const cstring &type, Util::JsonArray *&headers,
                                 const cstring &name) {
     auto u = new Util::JsonObject();
@@ -257,15 +241,12 @@ void JsonObjects::add_header_union_stack(const cstring &type, const cstring &nam
     header_union_stacks->append(stack);
 }
 
-/// Add an error to json.
 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 }
 void JsonObjects::add_enum(const cstring &enum_name, const cstring &entry_name,
                            const unsigned entry_value) {
     // look up enum in json by name
@@ -304,8 +285,6 @@ 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
 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];

backends/bmv2/common/JsonObjects.h

@@ -26,39 +26,173 @@ namespace BMV2 {
 
 class JsonObjects {
  public:
+    /// @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.
     static Util::JsonObject *find_object_by_name(Util::JsonArray *array, const cstring &name);
 
+    /// @brief Adds program information to the top-level JsonObject.
+    /// @param name The name of the program.
     void add_program_info(const cstring &name);
+
+    /// @brief Adds meta information to the JsonObject.
     void add_meta_info();
+
+    /// @brief Create a header type in json.
+    /// @param name header name
+    /// @param type header type
+    /// @param fields a JsonArray for the fields in the header
+    /// @param max_length  maximum length for a header with varbit fields; if 0 header does not
+    /// @return The ID of the newly created header type.
     unsigned add_header_type(const cstring &name, Util::JsonArray *&fields, unsigned max_length);
+
+    /// @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 add_union_type(const cstring &name, Util::JsonArray *&fields);
+
+    /// @brief Creates a header union instance in JSON.
+    /// @param type The type of the header union.
+    /// @param fields 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 add_union(const cstring &type, Util::JsonArray *&fields, const cstring &name);
+
+    /// @brief Create a header type with empty field list.
+    /// @param name header name
+    /// @param type header type
+    /// @param fields a JsonArray for the fields in the header
+    /// @param max_length  maximum length for a header with varbit fields; if 0 header does not
+    /// @return The ID of the newly created header type.
     unsigned add_header_type(const cstring &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 add_header_field(const cstring &name, Util::JsonArray *&field);
+
+    /// @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 add_header(const cstring &type, const cstring &name);
+
+    /// @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 add_metadata(const cstring &type, const cstring &name);
+
+    /// @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 add_header_stack(const cstring &type, const cstring &name, const unsigned size,
                           const std::vector<unsigned> &header_ids);
+
+    /// @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 add_header_union_stack(const cstring &type, const cstring &name, const unsigned size,
                                 const std::vector<unsigned> &header_ids);
+
+    /// @brief Adds an error to the JSON representation.
+    /// @param name The name of the error.
+    /// @param type The type of the error.
     void add_error(const cstring &name, const unsigned type);
+
+    /// @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 add_enum(const cstring &enum_name, const cstring &entry_name, const unsigned entry_value);
+
+    /// @brief Adds a parser to the JSON representation.
+    /// @param name The name of the parser.
+    /// @return The ID of the newly created parser.
     unsigned add_parser(const cstring &name);
+
+    /// @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 add_parser_state(const unsigned id, const cstring &state_name);
+
+    /// @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 add_parser_transition(const unsigned id, Util::IJson *transition);
+
+    /// @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 add_parser_op(const unsigned id, Util::IJson *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 add_parser_transition_key(const unsigned id, Util::IJson *key);
+
+    /// @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 add_parse_vset(const cstring &name, const unsigned bitwidth, const big_int &size);
+
+    /// @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 add_action(const cstring &name, Util::JsonArray *&params, Util::JsonArray *&body);
+
+    /// @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 add_extern_attribute(const cstring &name, const cstring &type, const cstring &value,
                               Util::JsonArray *attributes);
+
+    /// @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 add_extern(const cstring &name, const cstring &type, Util::JsonArray *attributes);
+
+    /// @brief Constructs a new JsonObjects instance.
+    /// Initializes the top-level JsonObject and other member arrays.
     JsonObjects();
+
+    /// @brief Inserts a JSON array into a parent object under a specified key.
+    /// @param parent The parent JsonObject to insert the array into.
     Util::JsonArray *insert_array_field(Util::JsonObject *parent, cstring name);
+
+    /// @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 *append_array(Util::JsonArray *parent);
+
+    /// @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 *create_parameters(Util::JsonObject *object);
+
+    /// @brief Creates a primitive JsonObject in a parent JsonArray with the given name.
+    /// @param parent The parent JsonArray in which the primitive will be created.
+    /// @param name The name of the primitive.
+    /// @return A pointer to the newly created primitive JsonObject.
     Util::JsonObject *create_primitive(Util::JsonArray *parent, cstring name);
-    // Given a field list id returns the array of values called "elements"
+
+    /// @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 *get_field_list_contents(unsigned id) const;
 
     std::map<unsigned, Util::JsonObject *> map_parser;