weixin_39717110
weixin_39717110
2020-12-08 19:12

Improve ConditionalAttribute documentation

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.

该提问来源于开源项目:dotnet/dotnet-api-docs

  • 点赞
  • 写回答
  • 关注问题
  • 收藏
  • 复制链接分享
  • 邀请回答

4条回答

  • weixin_39789979 weixin_39789979 4月前

    I'd like to add that the AttributeUsage attribute appears two times in the definition of the ConditionalAttribute.

    We should change

    csharp
    [System.AttributeUsage(System.AttributeTargets.Class | System.AttributeTargets.Method, AllowMultiple=true)]
    [System.Runtime.InteropServices.ComVisible(true)]
    [System.AttributeUsage(System.AttributeTargets.Method, AllowMultiple=true)]
    public sealed class ConditionalAttribute : Attribute
    

    to

    csharp
    [System.AttributeUsage(System.AttributeTargets.Class | System.AttributeTargets.Method, AllowMultiple=true)]
    [System.Runtime.InteropServices.ComVisible(true)]
    public sealed class ConditionalAttribute : Attribute
    
    点赞 评论 复制链接分享
  • weixin_39717110 weixin_39717110 4月前

    I think that's a separate issue that is already tracked at https://github.com/dotnet/docs/issues/6971.

    点赞 评论 复制链接分享
  • weixin_39855658 weixin_39855658 4月前

    , can you take a look at this feedback for the docs for ConditionalAttribute? Thanks.

    点赞 评论 复制链接分享
  • weixin_39598094 weixin_39598094 4月前

    I agree with the assessment.

    点赞 评论 复制链接分享