Conditional Compilation in XML Comments

Please support conditional compilation within XML documentation comments. This has been a source of pain since portable libraries came on the scene a while ago. Often linked code files are used to share source between different target platforms of the same API; however, as a result often times the documentation comments must change conditionally as well. As of now, there’s no good way around this limitation - you have to duplicate the entire XML comments conditionally, rather than just each section or line.

For example, I’d like to do this:

  /// <summary>
  /// Summary for Foo.
  /// </summary>
  /// <remarks>
  /// <para>Foo is great.</para>
#if !PORTABLE_403
  /// <para>Foo works well with <see cref="INotifyCollectionChanged"/>.<para>
#endif
  /// <para>Did I mention Foo is great?</para>
  /// </remarks>
  public void Foo() { ... }

INotifyCollectionChanged is not defined in .NET 4.0.3, so when targeting .NET 4.0.3 with a portable library the paragraph referencing it must be elided from the documentation.

[sharwell]

@gafter Do you still have the automated tool for moving these over? Depending on the role/scope I play in moving some of the documentation comment requests forward, I could certainly see this as one of the relevant ones.

🔗 This was already moved to dotnet/csharplang#295.

[NickCraver]

So, we have a use for this in Dapper as well, same situation since some members we <see cref /> aren’t in .NET Core. For example:

        /// <summary>
        /// Execute parameterized SQL and return an <see cref="IDataReader"/>
        /// </summary>
        /// <returns>An <see cref="IDataReader"/> that can be used to iterate over the results of the SQL query.</returns>
        /// <remarks>
        /// This is typically used when the results of a query are not processed by Dapper, for example, used to fill a <see cref="DataTable"/>
#if !COREFX
        /// or <see cref="DataSet"/>.
#endif
        /// </remarks>
        /// <example>
        /// <code>
        /// <![CDATA[
        /// DataTable table = new DataTable("MyTable");
        /// using (var reader = ExecuteReader(cnn, sql, param))
        /// {
        ///     table.Load(reader);
        /// }
        /// ]]>
        /// </code>
        /// </example>
        public static IDataReader ExecuteReader(

…which of course won’t compile. Can we get some love here?