Best practice for documenting std :: function parameters
When declaring a type with std::function
, I believe I missed the opportunity to assign parameter names to template arguments. For example, I find this simple function pointer type declaration:
typedef void (*ArcCallback)(
void *object,
double x_start, double y_start,
double x_finish, double y_finish,
double x_center, double y_center,
bool counterclockwise);
to be more readable than this type declaration std::function
:
typedef std::function<void(
void *,
double, double,
double, double,
double, double,
bool)> ArcCallback;
Despite the flexibility associated with usage std::function
(like being able to assign a lambda or the result of a call std::bind
), I am missing the parameter names. Of course, I can add comments to the ad std::function
, but the result is awkward. More importantly, I don't think IDEs will use these comments to provide parameter hints.
How do other seasoned C ++ professionals document the assignment of template parameters to std::function
? Is there a precedent set by widely used libraries that heavily use such types?
source to share
For this particular code, the problem is not so much that std::function
there is no good way to document the parameters, the problem is that 8 parameters are probably too many for any function. The introduction of additional types can greatly aid cleaning.
typedef void* CallbackObject;
struct Point {
double x;
double y;
};
enum CircularDirection {
CLOCKWISE,
COUNTERCLOCKWISE
};
struct ArcCallbackParam {
CallbackObject object;
Point start;
Point finish;
Point center;
CircularDirection direction;
};
typedef std::function<void(const ArcCallbackParam&)> ArcCallback;
Edit . I understand that this does not directly answer your question. To answer your question, I don't know of any "solutions" without commenting out the arguments, but adding types and typedefs can help a lot.
source to share
The parameter names in the original ArcCallback
typedef are for self-documentation purposes only. Since you are in the habit of using "redundant" parameter names for self-documentation purposes, why don't you do the same in the case std::function
?
typedef std::function<void (
void *object,
double x_start, double y_start,
double x_finish, double y_finish,
double x_center, double y_center,
bool counterclockwise)> ArcCallback;
The language does not prohibit doing this.
source to share