那是in或in/out参数吗? Doxygen，C ++ [英] Is that an in or in/out parameter? Doxygen, C++

问题描述

如果将指针传递给函数以进行只读，则该指针是一个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;
}

解决方案

我相信in和out指示符并不完全代表您的想法.从param标记的 doxygen文档:

\ param命令具有可选属性(dir)，用于指定 参数的方向.可能的值为"[输入]"，"[输入，输出]"， 和"[out]"，请注意本说明中的[方括号].当一个 参数既是输入也是输出，[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;
}

希望这会有所帮助！

If a pointer is passed to a function for read only, then this pointer is an IN parameter.

If a pointer is passed to a function for read only, but this function makes a copy of the pointer to have access to it in module related functions for read only operations, this pointer is still IN.

If the function still uses the pointer as read only, but the other module related functions use the pointer for write operations, what does that make the pointer? An IN parameter, but without const? An in/out parameter?

Example of what I mean:

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;
}

解决方案

I believe that the in and out specifiers do not exactly mean what you think. From the doxygen documentation of the param tag:

The \param command has an optional attribute, (dir), specifying the direction of the parameter. Possible values are "[in]", "[in,out]", and "[out]", note the [square] brackets in this description. When a parameter is both input and output, [in,out] is used as attribute.

The direction of the parameter usually mean the following:

• in: The parameter is injected into the function as input, but not written to.
• out: The parameter is injected into the function, but not as input. Rather, it is written to by the function.
• in, out: The parameter is injected into the function as input and is eventually written to by the function.

In your example:

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

I think the steeringWheel parameter is in because you inject it and use it in your method. However, you never write to it (i.e. to the parameter itself), so it is not out. In other words, you only use your method to inject an address to your function, nothing else. The same apply for your second method, where you inject the degree parameter, but never write to it.

To clarify a bit more on the meaning of in and out, here is an example of an out parameter:

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

Notice that we write a new value directly into the parameter. This is the meaning of out: information comes out of the method through the parameter. You can now write:

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;
}

Hope this helps!

这篇关于那是in或in/out参数吗? Doxygen，C ++的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！