epam / epam/Indigo

Refactor: Public APIs should be documented

Open
#3,387 0 comments 1 reaction 2 assignees Claimed by @AlexeyGirin View on GitHub
Priority: Low Severity: Low Sonar
Dominant language
C++
Stars
406
Forks
134
Avg merge
2d 11h
Merged PRs (30d)
24

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](https://www.sphinx-doc.org/en/master/).

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

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.