0

I'm writing a library with source code common to the server and the client.

The problem I have is inside XML comments, where sometimes the client and server documentation differs, something like:

  /// <summary>
  ///   Does something.
  /// </summary>
  /// <remarks>
  ///   Common info.
#if Client
  ///   Additional info for client only.
#endif
  /// </remarks>

When I compile without the Client symbol defined, I have the following warning:

Warning CS1570: XML comment has badly formed XML -- 'Expected an end tag for element 'remarks'.'
CS1570: XML comment has badly formed XML -- 'End tag was not expected at this location.'
Warning CS1587: XML comment is not placed on a valid language element

Is there a solution for this, or no hope?

Improve this question
7
  • based on some github issues "no hope" is more likely. Commented Nov 17, 2021 at 15:28
  • 1
    This sounds like an XY problem to me. If your having to do this it points at your design being incorrect Commented Nov 17, 2021 at 15:31
  • @Liam: why it is a design flow to have different documentation between client and server? One is dealing with SQL table and the other one with sending requests to the server. Commented Nov 18, 2021 at 4:32
  • Why haven't you got two classes then? Or use an implementation of an abstract class or some other design pattern. Your exposing the same contract for two pieces of functionality, that seems weird and confusing Commented Nov 18, 2021 at 9:57
  • @Liam First, the source code is compiled into two different assemblies, one for the server application and one for the client one. For both implementations, the properties, the documentation (almost) and some algorithms are the same, Having two different classes means that code will be duplicated. Commented Nov 18, 2021 at 12:50

2 Answers 2

Reset to default
4

This is currently not supported. Sorry.

In the official C# github repository, there is already a proposal for this feature:

However, this proposal is from 2017 and it's still tagged as "unanswered", so don't hold your breath.

As a side note, the comment thread in the proposal also contains an explanation for why this doesn't work: Those #if statements look like classic, C-style pre-processor directives, but they aren't. For example, you can write:

Console.WriteLine(@"

#if false
This is all inside the string and will get printed to the console
#endif

");

and the #... lines will end up in the string.

Improve this answer
Sign up to request clarification or add additional context in comments.

1 Comment

This is not exactly the same thing, as an XML comment ends at each line, so there is no problem with the code in the original post. Enabling #if in whole lines should be enough.
0

As this seems to not be possible in C#, I've created a small tool to post-process the XML comments file. This is a first version that currently meets my needs, but there are plenty of room for improvements.

Conditional XML comments

The XML comments should be (same as OP):

  /// <summary>
  ///   Does something.
  /// </summary>
  /// <remarks>
  ///   Common info.
  ///   <if symbol="client">
  ///   Additional info for client only.
  ///   </if>
  /// </remarks>

Running the tool

You can run the tool either:

  • In the post build events, so it is run automatically each time the solution is run.
  • In a command-line (batch file if multiple), so you can run it only when you need to generate the documentation.

The first argument of the program is the name of the XML comment file to process.

The following arguments are the names of the defined symbol.

The tool replaces the XML file with the processed one.

Source code

You can find the source code and information in GitHub repository

Improve this answer

Comments

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.