Function overloads, documentation almost identical [closed]

Closed. This question is seeking recommendations for books, tools, software libraries, and more. It does not meet Stack Overflow guidelines guidelines. It is not currently accepting answers.

---

We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.

开发者_运维知识库

Closed 5 years ago.

Improve this question

I have two acquire functions and, besides their arguments, the documentation is identical. How should I handle this? Should I add something like "The same general notes found in function X's documentation also apply here"? If not, does Doxygen offer some kind of tool for dealing with cases like this?

ResourcePtr<T> acquire(const std::string& file);
ResourcePtr<T> acquire(const void* buffer, std::size_t size);

---

I don't know Doxygen, so this answer is purely on my documentation approach.

When I document in a situation like where two topics are nearly identical, I either repeat the shared information in both (preferred) or I write something similar to the following:

"Function Y is similar to function X. Function Y takes the arguments abc and [put how it works differently here]...

For more information on these functions, see ."

In this case I'd document the simpler one and add the additional info to the more complex one.

A third way is to break out the common doc from both, if that's possible.

---

From This Page:

Use the \sa (See Also) keyword to link to related variables, methods, or classes. This is the equivalent command to \see tag.