What is the appropriate method to describe a valid range of a parameter in the documentation of code? Obviously long-form documentation (white papers, API documents, etc) can be more verbose than the actual code but this is really to address issues in the actual code than in the distributed documentation (that every user should read to begin with!)Examples:<argument name> where { <argument name> | 0 <= <argument name> <= 255 }<argument name> range: [0,255]<argument name> is valid between zero and 255 inclusive.
Documentation: What is appropriate when expressing a valid range for a parameter?
c++;documentation
If that's your valid range, I'd simply use a (signed) byte and let the compiler enforce it :-)Otherwise, any documentation form that you are happy with, which is intuitively understandable by the reader, and is technically correct and clear, is fine. I'd go for something brief and universally understandable like (0 <= arg <= 255).Another thing to consider is what does an out of range value cause to happen? In most cases, an out of range value will cause an effect (an assertion failure, a crash, an exception, an error return code, undefined behaviour?) so you may wish to document what will happen if an OOR input is provided. After all, you're documenting it so that callers know how to use it and what might happen if they get something wrong.