Incorrectly documented parameters identified by rst_parser.py (Bug #1205)
See the list attached.
Command to reproduce the list:
python2.6 -B modules/java/rst_parser.py all | grep "warning.*documented" > params.log
Fixed several false-positive warnings in rst_parser.py. (Now it detects 553 undocumented parameters for #1205.)
Vsevolod, we have discussed with Vadim what to do with differences in C and C++ argument's naming.
- In cases where we have simple difference, like lineType or line_type, please use C++ name for the C function. So, you can replace line_type with lineType and all similar occurrences.
- For a bit more complicated issues please create a txt-file highlighting the difference. We'll then decide if we should update the signatures, or just ignore these differences.
Made pull request
which allows to skip some warnings of the rst_parser.
Particularly, this pull request allows to skip the warning W007: parameter "..." is undocumented
Sometimes the documentation for such a parameter is not required (as an example, if there is a documented parameter
lineType, no need to document the parameter
line_type which is used in API 1.x variant of the function).
In this case we can add the commented line
.. :param line_type: (documentation isn't required)
and the warning won't be reported.
The line should start from "
.. param:" and should end by "
(documentation isn't required)"