We all know that a book should not be judged by its cover. However, a system can often be judged by its API, which may reveal many aspects of the internal implementation and the design choices of the system architects. A clear, readable, and easy-to-understand API is one of the most important features for an embedded system. Application developers expect to understand how to access functionalities quickly, to use the system in the most efficient way possible. The API represents the contract between the system and the applications, and for this reason, it must be designed beforehand and modified as little as possible, if at all, while the development moves towards the final delivery.
Some interfaces in the API may describe complex subsystems and abstract more elaborate characteristics, so it is always a good idea to provide adequate documentation to help application developers move around and exploit all the system capabilities. There are different ways to provide documentation along with the code, either distributing user manuals in the repository as separate files, or including the explanation of the different interfaces directly in the code.
The amount of comments in the code is not an indicator of quality. Comments have a tendency to age whenever the code they refer to gets modified, because of the possibility that the developer forgets to update the comment to match the new behavior in the code. Moreover, not all code needs to be commented: good habits, such as keeping functions short and low in complexity or using expressive symbol names, would make code comments redundant in most cases, as the code can explain itself. There are exceptions for lines of code that contain complex calculations, bit shifting, elaborate conditions, or side effects that are not easy to spot when reading the code for the first time. Some portions of code may also require a description at the beginning, for example, those functions with multiple return values and specific error handling. Switch/case statements not containing the break instruction between two cases must always have a comment to indicate that the fall-through is intended, and not a mistake. They should also possibly explain why some actions are grouped together between two or more cases. Adding superfluous comments that do not provide any valuable explanation of the code only contributes to make the code itself harder to read.
On the other hand, describing the behavior of a module with a separate editor and tools requires dedication, as all the documentation must be updated every time there are significant changes in the code, and the developers are asked to switch the focus away from the actual code.
Usually, the important part to document is the description of the contract mentioned previously, enumerating and explaining the functions and the variables that the applications and the other components involved can access at runtime. Since these declarations can be grouped within header files, it is possible to describe the entire contract by adding extended comments on top of the declaration of each exported symbol. Software tools exist that convert these comments into formatted documentation. A popular example is Doxygen, a free and open source document-generation tool that parses comments matching a specific syntax in the whole code base to produce hypertexts, structured PDF manuals, and many other formats. If the documentation is in the code base, updating and keeping track of its results is easier and less invasive for the developers' workflow. Integrating the generation of the documentation on the automation server can provide a freshly generated copy of the manuals for all the APIs at every commit on the master branch.