search

CESNET / ipfixcol

IPFIXcol is an implementation of an IPFIX (RFC 7011) collector
Other
64 stars 37 forks source link

Minor typos in doc-comments and Doxygen warnings #208

Closed SecDorks-TorchSis closed 5 years ago

SecDorks-TorchSis commented 5 years ago

There is also a major issue found while working on the last commit. Maybe a larger patch to fix the duplication of doc-comments between header and .c is needed.

Lukas955 commented 5 years ago

Thank you for your pull request.

I agree that duplicated Doxygen comments are problem. However, I don't fully agree with:

After all, header files are meant to be consumed by compilers, not by humans.

Especially, when I'm writing a code in an IDE, it's frequently faster for me to look into a header file of a module/component than looking for the particular section in parsed Doxygen documentation. Therefore, I prefer to follow simple rule: if the function is in a header file, I will put the doxygen comment there and leave the definition in the source file undocumented. It also requires that only function that should be accessible by user are in header files. Moreover, we are now focusing on development of IPFIXcol2 (https://github.com/CESNET/ipfixcol2), where we are already trying to avoid this issue by following the rule.

By the way, sorry for delay due to summer holidays.