Doxygen XML Tags for C#

Doxygen supports most of the XML commands that are typically used in C# code comments.
The XML tags are defined in Appendix E of the ECMA-334 standard, which defines the C# language. Unfortunately, the specification is not very precise and a number of the examples given are of poor quality.

Supported Tags by .NET / Visual Studio

The summary tag is the most basic of tags. The list below is the complete set currently supported by VS.NET

  • <c> The c tag gives you a way to indicate that text within a description should be marked as code. Use code to indicate multiple lines as code.
  • <code> The code tag gives you a way to indicate multiple lines as code. Use to indicate that text within a description should be marked as code.
  • <example> The example tag lets you specify an example of how to use a method or other library member. Commonly, this would involve use of the code tag.
  • <exception> The exception tag lets you specify which exceptions a class can throw.
  • <include> The include tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file.
  • <para> The para tag is for use inside a tag, such as or , and lets you add structure to the text.
  • <param> The param tag should be used in the comment for a method declaration to describe one of the parameters for the method.
  • <paramref> The paramref tag gives you a way to indicate that a word is a parameter. The XML file can be processed to format this parameter in some distinct way.
  • <permission> The permission tag lets you document the access of a member. The System.Security.PermissionSet lets you specify access to a member.
  • <remarks> The remarks tag is where you can specify overview information about a class or other type. is where you can describe the members of the type.
  • <returns> The returns tag should be used in the comment for a method declaration to describe the return value.
  • <see> The see tag lets you specify a link from within text. Use to indicate text that you might want to appear in a See Also section.
  • <seealso> The seealso tag lets you specify the text that you might want to appear in a See Also section. Use to specify a link from within text.
  • <summary> The summary tag should be used to describe a member for a type. Use to supply information about the type itself.
  • <value> The value tag lets you describe a property. Note that when you add a property via code wizard in the Visual Studio .NET development environment, it will add a tag for the new property. You should then manually add a tag to describe the value that the property represents.

Supported Tags by Doxygen

  • <c> Identifies inline text that should be rendered as a piece of code. Similar to using <tt>text</tt>.
  • <code> Set one or more lines of source code or program output. Note that this command behaves like \code ... \endcode for C# code, but it behaves like the HTML equivalent <code>...</code> for other languages.
  • <description> Part of a <list> command, describes an item.
  • <example> Marks a block of text as an example, ignored by doxygen.
  • <exception cref="member"> Identifies the exception a method can throw.
  • <include> Can be used to import a piece of XML from an external file. Ignored by doxygen at the moment.
  • <item> List item. Can only be used inside a <list> context.
  • <list type="type"> Starts a list, supported types are bullet or number and table. A list consists of a number of <item> tags. A list of type table, is a two column table which can have a header.
  • <listheader> Starts the header of a list of type "table".
  • <para> Identifies a paragraph of text.
  • <param name="paramName"> Marks a piece of text as the documentation for parameter "paramName". Similar to using \param.
  • <paramref name="paramName"> Refers to a parameter with name "paramName". Similar to using \a.
  • <permission> Identifies the security accessibility of a member. Ignored by doygen.
  • <remarks> Identifies the detailed description.
  • <returns> Marks a piece of text as the return value of a function or method. Similar to using \return.
  • <see cref="member"> Refers to a member. Similar to \ref.
  • <seealso cref="member"> Starts a "See also" section referring to "member". Similar to using \sa member.
  • <summary> Identifies the brief description. Similar to using \brief.
  • <term> Part of a <list> command.
  • <value> Identifies a property. Ignored by doxygen.

Here is an example of a typical piece of commented csharp code

  /// <summary>
  /// A search engine.
  /// </summary>
  class Engine
  {
      /// <summary>
      /// The Search method takes a series of parameters to specify the search criterion
      /// and returns a dataset containing the result set.
      /// </summary>
      /// <param name=&quot;connectionString&quot;>the connection string to connect to the database holding the content to search</param>
      /// <param name=&quot;maxRows&quot;>The maximum number of rows to return in the result set</param>
      /// <param name=&quot;searchString&quot;>The text that we are searching for</param>
      /// <returns>A DataSet instance containing the matching rows. It contains a maximum number of rows specified by the maxRows parameter</returns>
      public DataSet Search(string connectionString, int maxRows, int searchString)
      {
          DataSet ds = new DataSet();
          return ds;
      }
  }

Post new comment

  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • You can enable syntax highlighting of source code with the following tags: <code>, <blockcode>. The supported tag styles are: <foo>, [foo].
  • Lines and paragraphs break automatically.
  • No HTML tags allowed.
  • You can enable syntax highlighting of source code with the following tags: <code>, <blockcode>. The supported tag styles are: <foo>, [foo].
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.
By submitting this form, you accept the Mollom privacy policy.
© 2010 khype.org.. Drupal theme by Kiwi Themes.