Pragmas before types and members get dropped when porting docs into triple slash comments

[jeffhandley]

When porting API docs into triple slash comments, classes that have #if def pragmas wrapped around their access modifiers lose the first line of the pragma.

Given the following example, The #if USEPUBLIC pragma line is dropped.

#if USEPUBLIC
    public
#else
    internal
#endif
    class Foo { }

Expected

    /// <summary>Foo summary</summary>
#if USEPUBLIC
    public
#else
    internal
#endif
    class Foo { }

Actual

    /// <summary>Foo summary</summary>
    public
#else
    internal
#endif
    class Foo { }

This occurs with other types of pragmas as well. An example from Utf8Formatter.Guid.cs shows a scenario of an #endregion getting dropped.

Before

namespace System.Buffers.Text
{
    public static partial class Utf8Formatter
    {
        #region Constants

        private const byte OpenBrace = (byte)'{';
        private const byte CloseBrace = (byte)'}';

        private const byte OpenParen = (byte)'(';
        private const byte CloseParen = (byte)')';

        private const byte Dash = (byte)'-';

        #endregion Constants

        /// <summary>
        /// Formats a Guid as a UTF8 string.
        /// </summary>
        /// <param name="value">Value to format</param>
        /// <param name="destination">Buffer to write the UTF8-formatted value to</param>
        /// <param name="bytesWritten">Receives the length of the formatted text in bytes</param>
        /// <param name="format">The standard format to use</param>
        /// <returns>
        /// true for success. "bytesWritten" contains the length of the formatted text in bytes.
        /// false if buffer was too short. Iteratively increase the size of the buffer and retry until it succeeds.
        /// </returns>
        /// <remarks>
        /// Formats supported:
        ///     D (default)     nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
        ///     B               {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
        ///     P               (nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn)
        ///     N               nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn
        /// </remarks>
        /// <exceptions>
        /// <cref>System.FormatException</cref> if the format is not valid for this data type.
        /// </exceptions>
        public static bool TryFormat(Guid value, Span<byte> destination, out int bytesWritten, StandardFormat format = default)

After

namespace System.Buffers.Text
{
    /// <summary>Provides static methods to format common data types as Utf8 strings.</summary>
    public static partial class Utf8Formatter
    {
        #region Constants

        private const byte OpenBrace = (byte)'{';
        private const byte CloseBrace = (byte)'}';

        private const byte OpenParen = (byte)'(';
        private const byte CloseParen = (byte)')';

        private const byte Dash = (byte)'-';

        /// <summary>Formats a <see cref="System.Guid" /> as a UTF8 string.</summary>
        /// <param name="value">The value to format.</param>
        /// <param name="destination">The buffer to write the UTF8-formatted value to.</param>
        /// <param name="bytesWritten">When the method returns, contains the length of the formatted text in bytes.</param>
        /// <param name="format">The standard format to use.</param>
        /// <returns><see langword="true" /> if the formatting operation succeeds; <see langword="false" /> if <paramref name="buffer" /> is too small.</returns>
        /// <remarks>Formats supported:
        /// |Format string|Result string|
        /// |--|--|
        /// |D (default)|nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn|
        /// |B|{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}|
        /// |P|(nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn)|
        /// |N|nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn|
        /// If the method fails, iteratively increase the size of the buffer and retry until it succeeds.</remarks>
        public static bool TryFormat(Guid value, Span<byte> destination, out int bytesWritten, StandardFormat format = default)

[jeffhandley]

I have a very basic fix in the works for this. I'm adding tests for it, and I'm also considering a more thorough fix that would cover all types of leading trivia that need to be retained.

In places like this where leading trivia is loaded to be evaluated and potentially retained later, I'm considering getting all leading trivia instead of only getting specific sets of trivia. We could then pass the trivia collection through and replace the /// doc comment trivia with what is being ported in, but retain the other trivia.

My basic fix just collects all directive trivia and passes it through for it to be persisted. But that approach could leave other lurking bugs here for other types of trivia (that exist now or in the future).

@carlossanlop Feel free to assign this issue to me. And I'd appreciate your guidance on if you'd like me to try the approach of collecting all leading trivia and explicitly replacing triple slash comment trivia but retaining all other.

[jeffhandley]

@carlossanlop I have a draft PR up on my fork that shows what I've been working on for this: jeffhandley#1

Let me know if you think this approach is viable. If so, I can work on integrating it and doing some end-to-end testing.