dotnet / dotnet/dotnet-api-docs

Improve ConditionalAttribute documentation

Open
#3,522 4 comments 0 reactions 0 assignees View on GitHub
.net/prod area-System.Diagnostics doc-enhancement Pri2
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

I think `ConditionalAttribute` is one of the more confusing features of C#/.Net, so it's important that it's well documented.

Some of the ways in which the document could be improved:

* Make sure it's clear that when the C# compiler removes a call to a method, it also removes its receiver and parameters, which can have side-effects. See https://github.com/dotnet/roslyn/issues/28801. This should include updating both remarks and the example.
* Clarify the description of the example: it says it assumes using `/define`, but then the code has `#define`.
* Improve the example, so that `ConditionalAttribute` actually affects its output.
* Either make the list of ways of specifying conditional compilation symbols include the two that I think are most commonly used (use the VS IDE, edit .Net Core SDK .csproj) or link to an article that does.
* The article says that you can set conditional compilation symbols though environment variables. Is that really true?
* Remove mention of JScript, add F#.
* I don't understand the note about VB and `AddressOf`. If it's saying something useful, it should be clarified.

---
#### Document Details

⚠ *Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.*

* ID: 0380b9c1-45c7-2cad-4111-c3cb124d0663
* Version Independent ID: d2b35193-b11f-2cd9-7377-13c57c3f25a7
* Content: [ConditionalAttribute Class (System.Diagnostics)](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.conditionalattribute?view=netframework-4.7.2)
* Content Source: [xml/System.Diagnostics/ConditionalAttribute.xml](https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Diagnostics/ConditionalAttribute.xml)
* Product: **.net**
* GitHub Login: @mairaw
* Microsoft Alias: **mairaw**

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.