opencv注释中的@brief、@code/@endcode、@param、@sa 以及 如何在pycharm中看到opencv函数的完整注释

主要是参考opencv官方文档中的解释：

OpenCV: Writing documentation for OpenCV

一、说明

opencv在注释里面加入这些标志符号的原因是其使用了Doxygen这个程序，Doxygen这个软件可以通过标志符号将注释里面的内容收集起来组成一个完整的用户手册；简化了用户手册的制作过程。

@brief、@code/@endcode、@param、@sa这些符号都是Doxygen程序的语法需要。

二、符号的详细解释

例子：

cv2.exp() 有下面的注释

/** @brief Calculates the exponent of every array element.

The function exp calculates the exponent of every element of the input array:
\f[ \texttt{dst} [I] = e^{ src(I) } \f]

The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for
double-precision input. Currently, the function converts denormalized values to zeros on output.
Special values (NaN, Inf) are not handled.

@param src input array.
@param dst output array of the same size and type as src.

@sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
*/
CV_EXPORTS_W void exp(InputArray src, OutputArray dst);

1、/** ... */

special C-comment syntax denotes it is doxygen comment（说明其使用"C语言的注释方式"来实现它的doxygen注释）

2、@brief

command brief denotes following paragraph is a brief description（brief命令表示下面的段落是一个简短的解释）

3、空行

empty line denotes paragraph end（空行表示段落的结束。配合2、的。）

还可以看"三、"中的例子

4、\f[ ... \f]

TeX formula between f[ and f] commands（f[和f]之间的是LaTeX公式）

5、@param

command param denotes following word is name of the parameter and following text is description of the parameter; all parameters are placed in a list（param命令表示：首先接下来的单词就是参数的名字；然后再接下来的文字是对这个参数的介绍。所有的参数会被一个接一个全部列举出来。）

6、@sa

command sa starts "See also" paragraph containing references to some classes, methods, pages or URLs.（sa命令开始一个"See also"段落，该段落包含一些类/方法/页面/URLs的链接）

7、@code和@endcode

To mark some text as a code in documentation, code and endcode commands are used.（为了把一些文本标记为code，@code和@endcode命令被使用了）

8、@include

To include whole example file into documentation, include and includelineno commands are used. The file is searched in common samples locations, so you can specify just its name or short part of the path. The includelineno version also shows line numbers but prevents copy-pasting since the line numbers are included.

9、更多的符号，见opencv的文档网址

(本blog的第一行)

三、在pycharm中查看opencv函数的完整注释的方法

直接在pycharm的文件中执行help()命令

例子：

import cv2
help(cv2.resize)

返回：（可以在下面的内容中看到一些"空行"，这些空行就表示段落的结束）

Help on built-in function resize:

resize(...)
    resize(src, dsize[, dst[, fx[, fy[, interpolation]]]]) -> dst
    .   @brief Resizes an image.
    .   
    .   The function resize resizes the image src down to or up to the specified size. Note that the
    .   initial dst type or size are not taken into account. Instead, the size and type are derived from
    .   the `src`,`dsize`,`fx`, and `fy`. If you want to resize src so that it fits the pre-created dst,
    .   you may call the function as follows:
    .   @code
    .       // explicitly specify dsize=dst.size(); fx and fy will be computed from that.
    .       resize(src, dst, dst.size(), 0, 0, interpolation);
    .   @endcode
    .   If you want to decimate the image by factor of 2 in each direction, you can call the function this
    .   way:
    .   @code
    .       // specify fx and fy and let the function compute the destination image size.
    .       resize(src, dst, Size(), 0.5, 0.5, interpolation);
    .   @endcode
    .   To shrink an image, it will generally look best with #INTER_AREA interpolation, whereas to
    .   enlarge an image, it will generally look best with c#INTER_CUBIC (slow) or #INTER_LINEAR
    .   (faster but still looks OK).
    .   
    .   @param src input image.
    .   @param dst output image; it has the size dsize (when it is non-zero) or the size computed from
    .   src.size(), fx, and fy; the type of dst is the same as of src.
    .   @param dsize output image size; if it equals zero, it is computed as:
    .    \f[\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}\f]
    .    Either dsize or both fx and fy must be non-zero.
    .   @param fx scale factor along the horizontal axis; when it equals 0, it is computed as
    .   \f[\texttt{(double)dsize.width/src.cols}\f]
    .   @param fy scale factor along the vertical axis; when it equals 0, it is computed as
    .   \f[\texttt{(double)dsize.height/src.rows}\f]
    .   @param interpolation interpolation method, see #InterpolationFlags
    .   
    .   @sa  warpAffine, warpPerspective, remap

函数最后的括号不能加进去。