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?

Patrick8639
  • 31
  • 1
  • 7
  • based on some [github](https://github.com/dotnet/csharplang/discussions/295) issues "no hope" is more likely. – Guru Stron Nov 17 '21 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 – Liam Nov 17 '21 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. – Patrick8639 Nov 18 '21 at 04: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 – Liam Nov 18 '21 at 09: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. – Patrick8639 Nov 18 '21 at 12:50
  • Not if you do it correctly it won't. Build a base class, put all the shared logic in that, implement two child classes that inherit from the base class. No duplication, two contracts – Liam Nov 18 '21 at 13:20
  • #Liam Interesting possibility, but not in my case: the base classes also have client and server parts and they are inherited by other classes, so it complicates the thing. In addition, having different assemblies simplifies the references (for example, database library in server only). It also simplifies the consumers of the client assemblies because they don't see the server stuff in the API I prefer working with 2 assemblies partial classes: one file for the common part, one for client stuff and one for server stuff. – Patrick8639 Nov 18 '21 at 13:37

2 Answers2

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.

Heinzi
  • 167,459
  • 57
  • 363
  • 519
  • 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. – Patrick8639 Dec 16 '21 at 07:13
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

Patrick8639
  • 31
  • 1
  • 7