Using <Code> on current file

Aug 14, 2009 at 4:28 PM

I see in the help there are examples for using the <Code> element on external files or by embedding inline code between the opening and closing <Code> tags.  Is there a way to simply use the code being commented?  Any copy or external code means a maintenance and synchronization nightmare.  If I have the following method with comments, it makes a lot of sense to me to have the code element automatically pick up the code to which the XML comments apply.

        /// <summary>
        /// Writes the specified message to the COP ErrorLoggingWebService 
        /// web service with the specified category and specified LogMessageType.
        /// </summary>
        /// <param name="message">The message to write.</param>
        /// <param name="category">The category to mark the message with.</param>
        /// <param name="messageType">Whether the message is information, warning, or error.</param>
        /// <code SomeCommandToIncludeTheActualCode />
        public void Write(string message, string category, LogMessageType messageType)
        {
            if (initialized)
            {
                logService.InsertException(app, category, serverName, message, messageType.ToString());
            }
        }

Coordinator
Aug 14, 2009 at 7:33 PM

The <code> element is typically used to provide an example of using the given member being documented, not pull in the actual code that represents it.  The purpose of using an external file is to create a buildable example that you can verify is working.  If the underlying API changes such that it breaks the example, you know because the example project fails to build.  When you fix the example project and rebuild the help file, the example code in the help file is correct again based on those updates.

To do what you want, you'd most likely have to have a tool of some sort that processes the XML comments file and parses the source files to match up the <code> elements with their respective class members to insert the code.  That would probably involve parsing the source code in some way which could end up being rather language dependent.  I suppose you could use the PDB file in some way to extract information about the location of the members to get around that.

Eric