Incorrectly documented parameters identified by rst_parser.py (Bug #1205)


Added by Andrey Kamaev almost 6 years ago. Updated almost 2 years ago.


Status:Open Start date:
Priority:Normal Due date:
Assignee:Oleg Sklyarov % Done:

0%

Category:documentation
Target version:Next Hackathon
Affected version:branch '2.4' Operating System:
Difficulty: HW Platform:
Pull request:

Description

See the list attached.

Command to reproduce the list:

python2.6 -B modules/java/rst_parser.py all | grep "warning.*documented" > params.log


params.log - List of errors for r5903 (91.4 kB) Andrey Kamaev, 2011-07-07 05:00 pm

params.log - RST docs warnings (170.1 kB) Alexander Smorkalov, 2013-06-14 09:57 am


Associated revisions

Revision 94c258cf
Added by Andrey Kamaev about 5 years ago

#1205 fixed ~100 of ~700 parameters

Revision ec793df3
Added by Andrey Kamaev about 5 years ago

#1205 fixed more bugs/typos in parameters

Revision 7e5726e2
Added by Andrey Kamaev about 5 years ago

Fixed several false-positive warnings in rst_parser.py. (Now it detects 553 undocumented parameters for #1205.)

Revision 8f7ba03e
Added by Alexander Smorkalov almost 4 years ago

Some fixes for incorrectly documented parameters identified by rst_parser.py (Bug #1205)

History

Updated by Alexander Shishkov about 5 years ago

  • Subject changed from Incorrectly documented parametets idetrified by rst_parser.py to Incorrectly documented parameters identified by rst_parser.py

Updated by Kirill Kornyakov about 5 years ago

  • Target version set to 2.4.0

Updated by Alexander Shishkov about 5 years ago

  • Target version deleted (2.4.0)

Updated by Alexander Shishkov about 5 years ago

  • Priority changed from High to Low

Updated by Alexander Shishkov about 5 years ago

  • Assignee deleted (Vadim Pisarevsky)

Updated by Alexander Shishkov about 5 years ago

  • Target version deleted ()

Updated by Kirill Kornyakov over 4 years ago

Vsevolod, could you please inform about the current status? How many parameters are still incorrectly documented?

  • Priority changed from Low to Normal
  • Assignee set to Vsevolod Glumov
  • Target version set to 2.4.3

Updated by Vadim Pisarevsky over 4 years ago

ok, at least some of the problems could be fixed during hackathon

  • Target version deleted (2.4.3)
  • Assignee deleted (Vsevolod Glumov)

Updated by Vsevolod Glumov over 4 years ago

  • Assignee set to Vsevolod Glumov

Updated by Kirill Kornyakov over 4 years ago

Vsevolod, we have discussed with Vadim what to do with differences in C and C++ argument's naming.

  1. 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.
  2. 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.

Updated by Kirill Kornyakov over 4 years ago

  • Target version set to Next Hackathon

Updated by Kirill Kornyakov over 4 years ago

Oleg, since you're going to work on this regarding our needs, could you please update this ticket?

  • Assignee changed from Vsevolod Glumov to Oleg Sklyarov
  • Affected version set to branch '2.4'

Updated by Alexander Smorkalov almost 4 years ago

List of documentation warnings updated.

Updated by Leonid Beynenson almost 4 years ago

Made pull request
https://github.com/Itseez/opencv/pull/1009
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)"

Updated by Maksim Shabunin almost 2 years ago

Issue has been transferred to GitHub: https://github.com/Itseez/opencv/issues/4285

Also available in: Atom PDF