Reference common content from xml documentation file

Topics: Developer Forum, User Forum
Nov 12, 2012 at 8:51 PM
Edited Nov 12, 2012 at 8:52 PM

I am using  include tag to reference xml documentation file from my code and it works fine.

///<include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
public class Test

However I would like to reference some common content from that xml documentation file (one more xml doc file). For example:

<MyDocs><MyMembers name="test">
        <summary>
           <include file='common.xml' path='MyDocs/MyMembers[@name="test"]/*' />
        </summary>
</MyMembers></MyDocs>

Obviously it does not work this way. What is the right way of referencing common content? Probably there is some extension which can do it for me?

Coordinator
Nov 12, 2012 at 11:09 PM

If your intent is to inherit documentation from a base class or some other member, the inheritdoc tag will do what you need.

Eric

 

Nov 13, 2012 at 6:01 AM

I have resource file with all exception messages. Obviously I don't want to copy all messages into xml doc file and support both files. I'd like to reference the resource file from my xml doc. 

Coordinator
Nov 13, 2012 at 7:34 PM

You can use MAML token files to define the shared content and then add the API Token Resolution build component to the project's Component Configurations property.  It will add the token files to the API build and will convert the token elements to their given content when you build the project.

Add a token file to the project (it will have a .tokens extension and a build action of Tokens).  In it, you will create one token for each message.  The content of the token will be the XML comments to insert in place of the token name.  The token file editor will ensure that everything is saved in the proper format.  In your XML comments, all you need to do to reference the token is specify its name in a <token> tag like this:

/// <summary>
/// <token>ExceptionMessage1</token>
/// </summary>

Eric