In my cpp codebase, we have a set of return codes.
(let's say: enum class RC: UINT32 { kSucess, kNoMem, kIoError, kNetworkError ...} )
We use Doxygen and clang to enforce all kinds of coding conventions,
Specifically, every function must follow a documentation paragraph that references (using @param) every parameter, and also @return to explain the return value.
I want to know how can I use Doxygen/clang/any other lint tool, to enforce the function to declare all the different return codes it might return. (kind of like java's "throws")
example 1: (here all possible return codes are directly returned from the function, this is the naïve example)
/**
* findIdx searches for an item in the array and returns its index in the array
* (if found).
*
* @param pItem item to search its index in the array
* @param pArr the array to look search the item it
* @param len length of the array
* @param pOut output parameter, used to pass the item array index (if found)
*
* @return kInvalidArgs - if tried to search for null, or the array is null
* @return kNotFound - if searched array and does not contain pItem
* @return kSuccess - if the item was found and its index was passed via pOut
*/
RC findIdx(Item *pItem, Item *pArr[], unsigned int len, unsigned int *pOut)
{
if (pItem == nullptr || pArr == nullptr) {
return RC::kInvalidArgs;
}
for (int i = 0; i < len; i++) {
if (pArr[i] == pItem) {
*pOut = i;
return RC::kSuccess;
}
}
return RC::kNotFound;
}
example 2: (here some possible return codes might come from an indirect source, e.g. another function) NOTICE: the function declares in its return documentation all possible RC values, both direct and indirect
/**
* this is a wrapper of findIdx that also checks if a random number is even.
*
* @param ... same a before
*
* @return kInvalidArgs - ... same a before ...
* @return kNotFound - ... same a before ...
* @return kSuccess - ... same a before ...
* **@return kEvenRand - if the request encountered an even random value**
*/
RC findIdxWrapper(Item *pItem, Item *pArr[], unsigned int len, unsigned int *pOut)
{
if(std::rand() %2 == 0){
return RC::kEvenRand;
}else{
return findIdx(pItem, pArr, len, pOut);
}
}
Currently, we only enforce the appearance of a single @return and not the following content.
Our code base is missing a lot of possible error code, since without an automated check it's very hard to maintain: if someone edits a function, all callers (including indirectly) must edit their documentation.
e.g. in example 2, if findIdx changes adds return codes, findIdxWrapper must also change it's documentation.
Tried going around clang-tidy, Doxygen and other lint tools in search a way to configure them to do so, but didn't find what I needed.
