Is the XML <code> and <example> tags not supported?

[jonasrembratttetrapak]

I have a few projects that I'm currently adding (a lot of) XML documentation for but it seems the <code> tag does not yield "code block" markdown. Here's an example (XML):

   ///   <example>
   ///   <para>
   ///   This example shows an <c>async</c> method that fetches an object from a json file and returns
   ///   the outcome:
   ///   </para>
   ///   <code>
   ///   public async Task&lt;Outcome&lt;T&gt;&gt; GetFromFileAsync&lt;T&gt;(string path)
   ///   {
   ///       try
   ///       {
   ///           var json = await File.ReadAllTextAsync(path);
   ///           var item = JsonSerializer.Deserialize&lt;T&gt;(json);
   ///           return Outcome&lt;T&gt;.Success(item);
   ///       }
   ///       catch (Exception ex)
   ///       {
   ///           return Outcome&lt;T&gt;.Fail(ex);
   ///       }
   ///   }
   ///   </code>

This gets MD-rendered like this:

This example shows some client code that consumes an <see cref="T:TetraPak.Outcome`1"/> to fetch a <c>Car</c>
  
from the file system:
  
</para>
  
  
 public async Task&lt;Car&gt; GetCarAsync(string registrationNumber)
  
 {
  
    var filePath = getFilePathForCarWithRegistrationNumber(registrationNumber);
  
    var outcome = await GetFromFileAsync&lt;Car&gt;(filePath);
  
    if (!outcome)
  
    {
  
        _logger.Error(outcome.Exception, $"Failed when reading car: {registrationNumber}");
  
        throw outcome.Exception;
  
    }
  

  
    return outcome;
  
}
  
</code>

Seems the leading tag is simply removed while the closing tag is retained but no code block is being generated. Also, < and > aren't rendered as < and >. Am I doing something wrong or is this just not supported?

[Doraku]

they definitely are. I copy/pasted your xml input (with the closing </example> tag, not sure if it is missing on your end) and get this generated:

[jonasrembratttetrapak]

This is the full comment:

/// <summary>
    ///   Carries the outcome of an operation as well as any requested data, or an exception.
    ///   The class derives from the <c>abstract</c> <see cref="Outcome"/> class.
    /// </summary>
    /// <typeparam name="T">
    ///   The <see cref="Type"/> of data requested.
    /// </typeparam>
    /// <remarks>
    ///   <para>
    ///   The .NET try-convention when writing methods, such as
    ///   <see cref="Enum.TryParse(System.Type,string?,bool,out object?)"/> relies on returning a <see cref="bool"/>
    ///   value to reflect the outcome of the operation and, when successful, the requested value as an <c>out</c>
    ///   parameter. This is great for synchronous coding but doesn't fit the asynchronous paradigm as <c>out</c>
    ///   parameters are not allowed with <c>async</c> methods in C#.
    ///   </para>
    ///   <para>
    ///   The <see cref="Outcome{T}"/> is a simple solution to this problem, as it will return both the
    ///   outcome, the requested value (on success) or an <see cref="Exception"/> if the operation failed. 
    ///   </para>
    ///   <para>
    ///   <b>Implicit type casting</b>
    ///   </para>
    ///   <para>
    ///   An <see cref="Outcome{T}"/> value can be used to implicitly to test the outcome
    ///   (eg. <c>if (outcome)</c>) ...) or to get the expected value, when successful (eg. <c>Car car = outcome</c>).
    ///   Of course, if the expected value itself is a <see cref="bool"/> then you should avoid implicitly
    ///   type casting the value, as you would always get the "outcome", not the value.
    ///   </para>
    ///   <example>
    ///   <para>
    ///   This example shows an <c>async</c> method that fetches an object from a json file and returns
    ///   the outcome:
    ///   </para>
    ///   <code>
    ///       public async Task&lt;Outcome&lt;T&gt;&gt; GetFromFileAsync&lt;T&gt;(string path)
    ///       {
    ///           try
    ///           {
    ///               var json = await File.ReadAllTextAsync(path);
    ///               var item = JsonSerializer.Deserialize&lt;T&gt;(json);
    ///               return Outcome&lt;T&gt;.Success(item);
    ///           }
    ///           catch (Exception ex)
    ///           {
    ///               return Outcome&lt;T&gt;.Fail(ex);
    ///           }
    ///       }
    ///   </code>
    ///   <para>
    ///   This example shows some client code that consumes an <see cref="Outcome{T}"/> to fetch a <c>Car</c>
    ///   from the file system:
    ///   </para>
    ///   <code>
    ///        public async Task&lt;Car&gt; GetCarAsync(string registrationNumber)
    ///        {
    ///           var filePath = getFilePathForCarWithRegistrationNumber(registrationNumber);
    ///           var outcome = await GetFromFileAsync&lt;Car&gt;(filePath);
    ///           if (!outcome)
    ///           {
    ///               _logger.Error(outcome.Exception, $"Failed when reading car: {registrationNumber}");
    ///               throw outcome.Exception;
    ///           }
    ///       
    ///           return outcome;
    ///       }
    ///   </code>
    ///   </example>
    /// </remarks>

[Doraku]

yep <example> should be its top level tag, as <summary> and <remarks> here.

[jonasrembratttetrapak]

Ouch! My bad :-)
Thanks for your patience ...

[jonasrembratttetrapak]

I seems to have misunderstood Microsoft's XML doc guidelines:

https://docs.microsoft.com/en-au/dotnet/csharp/language-reference/xmldoc/recommended-tags

[Doraku]

Yeah they are not really clear, I think it was better explained in their previous documentation :/ Even in their dotnet api documentation they handle <example> as its own section https://docs.microsoft.com/en-us/dotnet/api/system.xml.linq.xelement.isempty?view=net-5.0#examples