Refactor: Public APIs should be documented

[Copilot]

Remove-me-section

Public Bingo NoSQL C APIs were undocumented, hindering generated customer-facing docs. Added concise Doxygen comments describing purpose, parameters, and return semantics.

• Changes
  • Documented all public functions in api/c/bingo-nosql/bingo-nosql.h, including search, insert, and profiling APIs.
  • Clarified pointer ownership and requirements (e.g., non-null output pointers, library-managed strings).
  • Fixed minor grammar in existing inline comment.
• Example

  /**
   * Estimates remaining search time.
   * \param search_obj Search iterator handle.
   * \param time_sec Pointer to a float that will be updated with the estimated seconds (must not be NULL).
   * \return 1 on success or -1 on error.
   */
  CEXPORT int bingoEstimateRemainingTime(int search_obj, float* time_sec);

Generic request

• PR name follows the pattern #1234 – issue name
• branch name does not contain '#'
• base branch (master or release/xx) is correct
• PR is linked with the issue
• task status changed to "Code review"
• code follows product standards
• regression tests updated

For release/xx branch

• backmerge to master (or newer release/xx) branch is created

Optional

• unit-tests written
• documentation updated

Backmerge request

• PR name follows the pattern Backmerge: #1234 – issue name
• PR is linked with the issue
• base branch (master or release/xx) is correct
• code contains only backmerge changes

Bump request

• PR name follows the pattern Bump version to ...
• add brackets [ ] for 'skip ci' and put it into the body
• milestone is linked to PR
• all tickets are closed inside the relevant milestone

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Refactor: Public APIs should be documented</issue_title>
<issue_description>Problem:
Public APIs should be documented

Why is this an issue?
Public APIs have to be documented in order to be used by customers.
APIs documentation is typically generated using a tool, such as Sphinx.

Exceptions that do not require documentation:

• Member functions marked with identifier override. Assumption is that they are documented in the base class.
• Member functions marked with specifier delete or default.
• Member functions defined outside of a class/struct. Assumption is that they are already documented inside of the class.

Following items are considered as public API:

• classes/structures/unions
• class/structure/union members (public and protected only)
• template declarations
• enumeration declarations
• enumeration definitions
• typedef/alias declarations
• functions (global scope)
• variables (global scope)

The following code illustrates a well documented class (example provided for python language):

    def setOption(self, option, value1, value2=None, value3=None):
        """Sets option value

        Args:
            option (str): option name
            value1 (int, str, bool, float): option value
            value2 (int, float): option value for tuples. Optional, defaults
                                 to None.
            value3 (float): option value for triple. Optional,
                            defaults to None.

        Raises:
            IndigoException: if option does not exist
        """

        opt = option.encode()
        if (
            isinstance(value1, float)
            and isinstance(value2, float)
            and isinstance(value3, float)
        ):
            IndigoLib.checkResult(
                self._lib().indigoSetOptionColor(opt, value1, value2, value3)
            )
        elif (
            isinstance(value1, int)
            and isinstance(value2, int)
            and value3 is None
        ):
            IndigoLib.checkResult(
                self._lib().indigoSetOptionXY(opt, value1, value2)
            )
        elif value2 is None and value3 is None:
            if isinstance(value1, str):
                setOpt = self._lib().indigoSetOption
                value = value1.encode()
            elif isinstance(value1, int):
                setOpt = self._lib().indigoSetOptionInt
                value = value1
            elif isinstance(value1, float):
                setOpt = self._lib().indigoSetOptionFloat
                value = value1
            elif isinstance(value1, bool):
                value1 = 0
                if value1:
                    value1 = 1
                setOpt = self._lib().indigoSetOptionBool
            else:
                raise IndigoException("bad option")
            IndigoLib.checkResult(setOpt(opt, value))
        else:
            raise IndigoException("bad option")

Problem locations:
api/c/bingo-nosql/bingo-nosql.h</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Refactor: Public APIs should be documented #3387

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.