doxygenの@warningと@attentionには何を書くか

@warningと@attentionの違いが今ひとつわからない。英語を母国語とするものにとっては明確に違うのかもしれない。意味が全然違うとか言われそうだ。しかし私にはわからないので調べてみる。

PCLのソースコード内を検索検索

ちょうど手元にあったPCLのソースコードでwarningとattentionを検索してみた。

attention

• @attention Holds a reference to the environment it was created from.
• \attention A second version of this function template exists which explicitly
• \attention It will be invoked from the new process.
• \attention alnum is equivalent to /[[:alnum:]]/ in perl. ~alnum is equivalent
• \attention keep(expr) is equivalent to the perl (?>…) extension.
• \attention Skipping does not affect how nested regexes are handled because
• \attention The default implementation doesn't do proper Unicode
• \attention Not currently used
• \attention Since 1.4.0, Eigen matrices are forced to Row Major to increase the efficiency of the algorithms in PCL
• \attention The input normals given by setInputNormalsSmall and setInputNormalsLarge have
• @attention untested code
• \attention The focal length may change, depending whether the depth stream is registered/mapped to the RGB stream or not.
• \attention its not the system time, thus can not be used directly to synchronize different sensors.
• \attention The PCD data is \b always stored in ROW major format!
• \attention This method does not do any bounds checking for the input index

warning

• \warning If the launching and the child process use the input, this leads to undefined behaviour.
• \warning This feature requires boost/process/async.hpp to be included and a reference to boost::asio::io_service to be passed to the launching function.
• \warning Invalid arguments cause undefined behaviour.
• \warning Throwing an exception may cause data loss. This will also throw if a small vector resize throws, in which case there will be no data loss.
• \warning This method will be removed in the future. Use setNegative() instead.
• \warning The vertices must be valid and unique (each vertex may be contained only once). Not complying with this requirement results in undefined behavior!
• \warning Please make sure to NOT add or remove elements from the cloud.
• \warning Does NOT check if the stored mesh pointer is valid. You have to ensure this yourself when constructing the circulator.
• \warning The vertices must be valid and unique (each vertex may be contained only once). Not complying with this requirement results in undefined behavior!
• \warning PCLPointCloud2 inserted into the tree must have x,y,z fields, and must be of same type of any other points inserted in the tree
• @warning Image type changes if a calibration pattern is discovered/lost;
• @warning This functionality is not supported with the legacy OpenGL backend.

所感

@attention ... 使う上で考慮しておくべき項目など。たとえば、 @attention untested code などは使ってはいけないとも、使うと問題が起こるとも限らないが、考慮必須の項目である。

@warning ... やってはいけない使い方・問題が起こる条件など。たとえば、
\warning Invalid arguments cause undefined behaviour. は無効な引数に対して動作保証がないことを示している。