How to specify a type in an XML comment Comment <return>

In a comment on a C # XML Comment <return> I would like the result (I use Sandcastle) to indicate the return type, but I can't figure out how to do this.

Psuedo example:

 ///<summary> ///Serves as a hash function for a particular type. ///</summary> ///<returns **Type="System.Int32"**> ///A hash code for the current Object. ///</returns> public virtual int GetHashCode(){...} 

The above example is a layout that I suppose should tell Sandcastle how to specify the return type that is documented in the Syntax section of the documentation - not like that.

For clarity, a screenshot of the MSDN documentation of the GetHastCode () method is shown , which shows the type of the returned object, which I shoot for,

Is it necessary to manually specify Type, or can we indicate Type (similar to the mock example), and let Sandcastle determine how to display / format the output - just like Sandcastle automatically displays / formats Type for parameters via the <param> .

enter image description here

+6
source share
2 answers

This post (July 2011) has a response from Eric Woodruff (SHFB Author) regarding the lack of return type displayed in <return> :

Sandcastle does not display type information for the return, and I do not think it ever was. If the information in the XSL transform reflection information file can be modified for rendering. I don’t have time to study it now, but I can at some point be able to figure out if this is possible.

I believe the official answer to my OP; Sandcastle does not have an automatic way to specify the type of return, but, as mentioned in Skeet, it can do this by changing XSL transformations.

+2
source

You do not need to specify it in the XML documentation - in the end, that would be superfluous, given that it is in the method declaration.

I suspect it's a matter of setting the Sandcastle style if you really want to, but do you find it particularly useful? This is not the case, as users cannot simply click on the return type in the method signature. (At least this is similar to the Prototype style in SHFB. See the Noda Time Documentation for an example of how it looks.)

On MSDN, then the method signature has no references (at least not in Chrome, I don’t know if it differs in IE), but personally I would prefer it to be in the signature instead of cluttering the actual documentation.

+4
source

Source: https://habr.com/ru/post/909025/


All Articles