这是一个输入或输入/输出参数吗？氧，C++答案

【问题标题】：Is that an in or in/out parameter? Doxygen, C++这是一个输入或输入/输出参数吗？氧，C++
【发布时间】：2018-05-23 18:43:19
【问题描述】：

如果一个指针被传递给一个只读函数，那么这个指针就是一个 IN 参数。

如果一个指针被传递给一个只读函数，但是这个函数复制了一个指针以便在模块相关函数中访问它以进行只读操作，这个指针仍然是IN。

如果函数仍然使用指针作为只读，但其他模块相关的函数使用指针进行写操作，那么指针是什么？一个 IN 参数，但没有 const？输入/输出参数？

我的意思的例子：

class SteeringWheel {
        public: float rotation;
        public: SteeringWheel(void) {
                this->rotation = 0.f;
        }
};

class Car {
        private: SteeringWheel *steeringWheel;
        public:

        /**
         * @param[?] steeringWheel Is the steering wheel in or in/out? 
         */
        Car (SteeringWheel *steeringWheel) {
                this->steeringWheel = steeringWheel;
        }

        /**
         * @param[in] degree Steering amount in degrees.
         */
        void steer(float degree) 
        {
                this->steeringWheel->rotation += degree;
        }
};

int main(int argc, char **argv)
{
        SteeringWheel steeringWheel();

        /* car() uses steeringWheel as read only. */
        Car car(&steeringWheel);

        /* steer() uses steeringWheel from car() to write. */
        car.steer(50.f);

        return 0;
}

【问题讨论】：

标签： documentation doxygen inout

【解决方案1】：

我相信in 和out 说明符并不完全符合您的想法。来自doxygen documentation of the param tag：

\param 命令有一个可选属性 (dir)，指定参数的方向。可能的值为 "[in]"、"[in,out]"、和“[out]”，请注意此描述中的 [square] 括号。当一个参数既是输入又是输出，[in,out]作为属性。

参数的方向通常有以下含义：

in：参数作为输入注入到函数中，但没有写入。
out：参数被注入到函数中，但不作为输入。相反，它是由函数写入的。
in, out：参数作为输入注入到函数中，最终被函数写入。

在你的例子中：

/**
* @param[?] steeringWheel Is the steering wheel in or in/out? 
*/
Car (SteeringWheel *steeringWheel) {
    this->steeringWheel = steeringWheel;
}

我认为steeringWheel 参数是in，因为您将其注入并在您的方法中使用它。但是，您永远不会写入它（即参数本身），所以它不是out。换句话说，您只使用您的方法将地址注入您的函数，没有别的。这同样适用于您的第二种方法，您注入 degree 参数，但从不写入。

为了更清楚地了解in 和out 的含义，下面是out 参数的示例：

/**
 * @param[out] p_param We write to the parameter!
 */
void makeFour(int * p_param)
{
    *p_param = 4; // Out because of this line!
}

请注意，我们将新值直接写入参数。这就是out的意思：信息通过参数从方法中出来。你现在可以写：

int main()
{
    int myInt = 0;
    std::cout << myInt;    // prints 0.

    makeFour(&myInt); // p_param == &myInt here.
    std::cout << myInt;    // prints 4: the method wrote directly 
                           // in the parameter (out)!

    return 0;
}

希望这会有所帮助！

【讨论】：

【解决方案2】：

这并不容易决定，但我仍然会将您的参数标记为in,out（或out），因为它是一个指向非常量对象的指针，您可以稍后直接或间接更改该外部对象的状态 - 就像您的示例一样。

将其标记为in 隐藏了指向SteeringWheel 对象可能在以后使用Car 时更改的细节。

另外，它可能会让用户感到困惑，为什么只输入指针参数没有标记const。

设为in,out 可能不完全准确，但肯定更容易出错。

替代方案可能类似于以下内容（无论如何，关于 SteeringWheel 的生命周期的注释在这里应该派上用场）：

    /**
     * @param[in] steeringWheel Pointer to the SteeringWheel object.
     * @warning The memory address of the pointed object is saved.
     * It must outlive this object, and can change upon usage of this object.
     */
    Car (SteeringWheel *steeringWheel) {
            this->steeringWheel = steeringWheel;
    }

但我可能会坚持标记为in,out。

在 C++ 中指定参数的方向可能很复杂，坦率地说，我不太赞成它们，因为指针、引用的标记和 constness 的关键字在签名中提供了足够的信息来说明可以使用参数。因此，在 DoxyPress 文档中标记它有点多余，不够表达（如您的示例所示），并且可能与实现不同步。如果其他语言在函数签名中缺乏这些额外的结构，记录参数方向可能会发挥更大的作用。

【讨论】：