C#: is it possible to have "Description" annotation on enums?

[bibekdw]

Do we have an option to populate description annotation on enums? It would be really handy if we can have something like : C#

public enum MyEnum
{
    Name1 = 1,
    [Description("Here is another")]
    HereIsAnother = 2,
    [Description("Last one")]
    LastOne = 3
}

Java

public enum service{
     @Description(name="describe serv1")
     ser1,
     @Description(name="blabla")
     ser2,
     @Description(name="sjfsfs")
     ser3,
}

[GreyCat]

We do have verbose enums, which allow to generate per-entry docstrings. But I don't think that they generate thse Description annotations. How standard are they?

[bibekdw]

I think it is pretty common at least in C# and Java world. Since enumerations cannot have space or any special chars, while showing on the UI, you can directly get the Description for particular enumeration. It used to be tedious to have separate mapping for each enum value.

So is the doc attribute from verbose enums is accessible while generating the code for enums? If it is, it would not be so difficult to implement I guess.

[GreyCat]

Well, I can't say for C#, but at the very least I haven't seen it in Java world. And, from what I know of Java, you need to either define that description annotation as a class or import it. According to this SO question, it seems that there's no standard Java class for that.

[bibekdw]

I take it back, you are right, java does not seems to have standard class. But C# has built in class for that.

[GreyCat]

Cc our C# experts @LogicAndTrick @indrora @koczkatamas @arekbulski — what do you guys think of this proposal? Are there any potential pitfalls here, like this annotation having negative performance impact or anything?

[tmillican]

Edit: Nevermind. PEBKAC.

~~I'm not a C# expert, but here's one potential issue:~~

~~At least according to Microsoft's .NET API browser, System.ComponentModel.DescriptionAttribute isn't implemented in the .NET Core 2.0 SDK/runtime. This is weird, because it's part of the .NET Standard 2.0 API surface, which .NET Core 2.0 is supposed to implement. It is implemented in .NET Core 2.1 Preview 2.~~

~~That being said, I didn't have an trouble getting such a program to compile with .NET Core SDK 2.1.200, or with running it on .NET Core runtime 2.0.7, which are the latest non-preview versions.~~

~~I don't know which API surface you intend to support, so that may all be moot.~~

In terms of runtime performance, it shouldn't make any significant difference. The descriptions attributes are just objects that are allocated once per runtime invocation, and (I think) they use lazy evaluation to boot. So if you don't use reflection, attributes, etc. there's no meaningful runtime penalty. Compiler overhead is a once-per-assembly tax of about 80 extra lines of code.

[bibekdw]

@tmillican System.ComponentModel.DescriptionAttribute seems to be available in .Net core 2.0. Do you mean missing in .Net core 1.1?

[tmillican]

Disregard that; I don't know what happened. When I checked earlier it wasn't there. I must have clicked the wrong .Net Core version by accident.

[indrora]

I've personally never used the Description annotation on a member of an enum.

Is there any harm generating them? Not really.

What sort of complexity does this add to the ksy tree though?

[GreyCat]

What sort of complexity does this add to the ksy tree though?

The original idea was to avoid changing anything in ksy. There's already doc tag supported on individual enum members that could be used to generate these annotations.

[indrora]

I'd suggest making it an option to turn on which defines the behavior of various .NET attribute classes.

Specifically, the DescriptionAttribute is intended as a way to show help in a PropertyGrid control and similar sorts of control elements:

Perhaps this needs to be a C#/.NET specific generator option? Dunno if other languages have such things (I know Java sort of does with annotations, but I don't know that there's a standard set of names for them)