What is the correct way to document the expected parameter for multiple functions?

Topics: Developer Forum, User Forum
Feb 4, 2013 at 3:26 PM
Edited Feb 4, 2013 at 3:28 PM
Given a selection of functions, where is the best place to document the concept of specific variables that are used as the input parameters and return values of multiple functions?

My key concern is making this information easily accessible for those who are referring to the documentation of any of such specific function, whilst keeping repetition to a minimum.
int GetMaskFromOrientationName(string name);
string GetNameFromOrientationMask(int mask);
int CountConnectionsBetweenOrientations(int maskA, int maskB);
For example, somebody reading about CountConnectionsBetweenOrientations might not know what a mask is. Likewise the same for the other two functions.
Coordinator
Feb 4, 2013 at 8:01 PM
If the information is conceptual in nature such as the definition of a mask and how it is used, you could create a MAML topic and use a conceptualLink element in the XML comments of each member to link to the common topic. Placing the link within a remarks element for example would create an inline link. Placing it at the top level outside of all other elements would treat it like a seealso link and would put it in the See Also section of the topic.

If your goal is just to share certain parts of the XML comments between the three methods, you could place the common elements on one of the methods and use the inheritdoc element with cref and select attributes to pull in information from the other member.

Eric
Feb 5, 2013 at 3:08 PM
If the information is conceptual in nature such as the definition of a mask and how it is used, you could create a MAML topic and use a conceptualLink element in the XML comments of each member to link to the common topic. Placing the link within a remarks element for example would create an inline link. Placing it at the top level outside of all other elements would treat it like a seealso link and would put it in the See Also section of the topic.
That's a good idea, this information is more conceptual in nature.

Thanks for the tip :-)