Is there a way to document overloaded methods
-
/// <summary>
/// Great big long multiline explanation of foo()
/// </summary>
public void foo() {...}/// <summary>
/// same great big long explanation again
/// </summary>
/// <parm name="x">Put a number here</param>
public void foo(int x) {...}/// <summary>
/// same great big long explanation yet again
/// </summary>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void foo(int x, int y) {...}
...There has to be a better way... anyone?
Clive Pottinger Victoria, BC
-
/// <summary>
/// Great big long multiline explanation of foo()
/// </summary>
public void foo() {...}/// <summary>
/// same great big long explanation again
/// </summary>
/// <parm name="x">Put a number here</param>
public void foo(int x) {...}/// <summary>
/// same great big long explanation yet again
/// </summary>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void foo(int x, int y) {...}
...There has to be a better way... anyone?
Clive Pottinger Victoria, BC
It shows up in intellisense. I suppose the only better way is to put it in the design document.
Need a C# Consultant? I'm available.
Happiness in intelligent people is the rarest thing I know. -- Ernest Hemingway -
/// <summary>
/// Great big long multiline explanation of foo()
/// </summary>
public void foo() {...}/// <summary>
/// same great big long explanation again
/// </summary>
/// <parm name="x">Put a number here</param>
public void foo(int x) {...}/// <summary>
/// same great big long explanation yet again
/// </summary>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void foo(int x, int y) {...}
...There has to be a better way... anyone?
Clive Pottinger Victoria, BC
NDoc supports an "<overloads>" XML comment, but I'm not sure if SandCastle also supports it. There really isn't any other way currently.
Scott Dorman
Microsoft® MVP - Visual C# | MCPD President - Tampa Bay IASA Hey, hey, hey. Don't be mean. We don't have to be mean because, remember, no matter where you go, there you are. - Buckaroo Banzai
-
It shows up in intellisense. I suppose the only better way is to put it in the design document.
Need a C# Consultant? I'm available.
Happiness in intelligent people is the rarest thing I know. -- Ernest HemingwayWell, not only does the current method mean having the same description entered over and over, but it is also prone to errors. I have a number of these kind of functions where foo() and foo(int x) both end up calling foo(int x, int y). If I make a change to foo(int x, int y) and alter its documentation, I have to make sure that I go back and alter the documentation for the other two - which, sometimes I miss, or do incorrectly. I was hoping for something more along the lines of
/// <summary>
/// Great big long multiline explanation of foo()
/// </summary>
public void foo() {...}/// <summary autodoc=foo()/>
/// <parm name="x">Put a number here</param>
public void foo(int x) {...}/// <summary autodoc=foo()/>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void foo(int x, int y) {...}
...Something that would save typing the same function description over and over. And while I'm in pie-in-the-sky-land,
/// <summary autodoc=foo()>
/// but, unlike foo(), this method does not accept negative values.
/// </summary/>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void goo(int x, int y) {...}
...Clive Pottinger Victoria, BC
-
Well, not only does the current method mean having the same description entered over and over, but it is also prone to errors. I have a number of these kind of functions where foo() and foo(int x) both end up calling foo(int x, int y). If I make a change to foo(int x, int y) and alter its documentation, I have to make sure that I go back and alter the documentation for the other two - which, sometimes I miss, or do incorrectly. I was hoping for something more along the lines of
/// <summary>
/// Great big long multiline explanation of foo()
/// </summary>
public void foo() {...}/// <summary autodoc=foo()/>
/// <parm name="x">Put a number here</param>
public void foo(int x) {...}/// <summary autodoc=foo()/>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void foo(int x, int y) {...}
...Something that would save typing the same function description over and over. And while I'm in pie-in-the-sky-land,
/// <summary autodoc=foo()>
/// but, unlike foo(), this method does not accept negative values.
/// </summary/>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void goo(int x, int y) {...}
...Clive Pottinger Victoria, BC
Updating documentation is an expensive and time consuming process. Considering the bad results I have seen from automated tools causing developers to use inferred documentation I am a big fan of the manual process. Also, in general, an overloaded method should do the same thing as all of the other methods but with different parameters. Causing special handling is asking for disaster.
Need a C# Consultant? I'm available.
Happiness in intelligent people is the rarest thing I know. -- Ernest Hemingway -
Well, not only does the current method mean having the same description entered over and over, but it is also prone to errors. I have a number of these kind of functions where foo() and foo(int x) both end up calling foo(int x, int y). If I make a change to foo(int x, int y) and alter its documentation, I have to make sure that I go back and alter the documentation for the other two - which, sometimes I miss, or do incorrectly. I was hoping for something more along the lines of
/// <summary>
/// Great big long multiline explanation of foo()
/// </summary>
public void foo() {...}/// <summary autodoc=foo()/>
/// <parm name="x">Put a number here</param>
public void foo(int x) {...}/// <summary autodoc=foo()/>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void foo(int x, int y) {...}
...Something that would save typing the same function description over and over. And while I'm in pie-in-the-sky-land,
/// <summary autodoc=foo()>
/// but, unlike foo(), this method does not accept negative values.
/// </summary/>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void goo(int x, int y) {...}
...Clive Pottinger Victoria, BC
I know this doesn't help you with the problem at hand, but I think you'll do just fine - you already use and think about documentation FAR more than most people I know. :)
Cheers, Vikram.
The hands that help are holier than the lips that pray.
-
Well, not only does the current method mean having the same description entered over and over, but it is also prone to errors. I have a number of these kind of functions where foo() and foo(int x) both end up calling foo(int x, int y). If I make a change to foo(int x, int y) and alter its documentation, I have to make sure that I go back and alter the documentation for the other two - which, sometimes I miss, or do incorrectly. I was hoping for something more along the lines of
/// <summary>
/// Great big long multiline explanation of foo()
/// </summary>
public void foo() {...}/// <summary autodoc=foo()/>
/// <parm name="x">Put a number here</param>
public void foo(int x) {...}/// <summary autodoc=foo()/>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void foo(int x, int y) {...}
...Something that would save typing the same function description over and over. And while I'm in pie-in-the-sky-land,
/// <summary autodoc=foo()>
/// but, unlike foo(), this method does not accept negative values.
/// </summary/>
/// <parm name="x">Put a number here</param>
/// <parm name="y">Put a second number here</param>
public void goo(int x, int y) {...}
...Clive Pottinger Victoria, BC
You might want to look at the <include>[^] tag.
Scott Dorman
Microsoft® MVP - Visual C# | MCPD President - Tampa Bay IASA Hey, hey, hey. Don't be mean. We don't have to be mean because, remember, no matter where you go, there you are. - Buckaroo Banzai
-
NDoc supports an "<overloads>" XML comment, but I'm not sure if SandCastle also supports it. There really isn't any other way currently.
Scott Dorman
Microsoft® MVP - Visual C# | MCPD President - Tampa Bay IASA Hey, hey, hey. Don't be mean. We don't have to be mean because, remember, no matter where you go, there you are. - Buckaroo Banzai
Thanks, Scott. That looks pretty good. Unfortunately, it is not recognised by VS. I must say that I am surprised that this seems to have been overlooked when the XML documentation ability was being created. It seems (to me, at any rate) to be an obvious feature to be included - much more so than the <seealso> or <include> tags. But, I'm still hoping one you guru's out there knows a way...
Clive Pottinger Victoria, BC
-
Thanks, Scott. That looks pretty good. Unfortunately, it is not recognised by VS. I must say that I am surprised that this seems to have been overlooked when the XML documentation ability was being created. It seems (to me, at any rate) to be an obvious feature to be included - much more so than the <seealso> or <include> tags. But, I'm still hoping one you guru's out there knows a way...
Clive Pottinger Victoria, BC
cpotting wrote:
I must say that I am surprised that this seems to have been overlooked when the XML documentation ability was being created. It seems (to me, at any rate) to be an obvious feature to be included - much more so than the <seealso> or <include> tags.
I agree. You may want to check the Sandcastle documentation, as it may support the overloads tag.
Scott Dorman
Microsoft® MVP - Visual C# | MCPD President - Tampa Bay IASA Hey, hey, hey. Don't be mean. We don't have to be mean because, remember, no matter where you go, there you are. - Buckaroo Banzai