You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
It would be great if PublicApiGenerator "understood" NullableAttribute, so could print out the API with suitable ? syntax.
Trickier: exposing whether an API is null-aware at all.
Technically PublicApiGenerator already understands it because it has the ability to print out attributes as well as the constructor values of the attributes. You are asking for is custom code that translates the existence of
public void X([NullableAttribute(1)] string input) {}
public void Y([NullableAttribute(2)] string input) {}
to
public void X(string input) {}
public void Y(string? input) {}
and obviously also all the other cases you mentioned in your post?
I'm wondering what the value proposition of that mapping would be given that already today you get the API surface with all the necessary information. I think the value proposition would be that you might get better readability?
Yes, readability is the key here - particularly when it comes to generics. I would like users not to have to wonder what [NullableAttribute(new byte[] { 1, 2, 1 })] Dictionary<string, string> map means, for example.
I have more feature requests to add when I'm on a laptop. I may be able to implement some myself, but I wanted to just get them out of my head first :)
changed the title [-]Feature request: C# 8 nullable refernece type support[/-][+]Feature request: C# 8 nullable reference type support[/+]on Feb 11, 2019
Not sure I have a feasible way of implementing this without considerably revamping how the code currently works. The problem is that the current code turns everything into a CodeDom and then writes that into a string writer. So in order to pretty print the types and things annotated with NullableAttribute I would need to do some intensive string replacing logic that covers all the special cases. If you have a good idea on how to achieve this without redesigning the whole ApiGenerator I'm all ears.
I have conflicting feelings about this change. On the one hand, it seems that the proposal is really good. On the other hand, the current way of representing this information through attributes seems to be cleaner.
The compression scheme for the byte array passed to NullableAttribute for things with nested nullability is not something I'm capable of mentally unwinding, either.
@jskeet This means that we will have to do all the dirty work of reversing the conversion of type information from attributes — decompression, move bits around, matching, etc. All to solve the inverse problem of the compiler.
It's all clear. We can say that these attributes are special, although they are only attributes. On the other hand, someone may want to ignore these attributes. Now it is possible to do since code does not interpret them in a special way.
I don't think anyone will want to ignore them any more than they'd want to ignore [TupleElementNames(...)] etc (which should also be decoded and written using proper C# syntax). It's API stuff that you are shipping to the world; you should not be able to opt out of seeing what you are doing.
I ran commit 677fd84 2019-11-02 | tests against the entirety of https://www.nuget.org/packages/Microsoft.NETCore.App.Ref/3.0.0 (151 assemblies, 22 annotated) and both searched for all nullability syntax and visually scanned the files. Nothing looks wrong to me besides what I've already reported. There was some good variety.
I noticed a new thing which is actually more of a problem than the encoded NullableAttribute appearing. The [NotNull], [MaybeNullWhen(...)], [DoesNotReturn] etc attributes are not showing up at all. This is a separate problem and I'll open a new issue once I know more.
The issue is that internal attributes aren't shown. Anyone working with nullable reference types on target frameworks other than netcoreapp3.0+ or netstandard2.1+ will need #117.
No, but the implementation for #117 will not be related at all to the work in this thread and I think it will be dramatically easier. You already have logic to show or hide attributes, so we augment that by checking against a list of full attribute type names that must never be hidden.
Activity
danielmarbach commentedon Feb 11, 2019
Technically PublicApiGenerator already understands it because it has the ability to print out attributes as well as the constructor values of the attributes. You are asking for is custom code that translates the existence of
to
and obviously also all the other cases you mentioned in your post?
I'm wondering what the value proposition of that mapping would be given that already today you get the API surface with all the necessary information. I think the value proposition would be that you might get better readability?
jskeet commentedon Feb 11, 2019
Yes, readability is the key here - particularly when it comes to generics. I would like users not to have to wonder what
[NullableAttribute(new byte[] { 1, 2, 1 })] Dictionary<string, string> mapmeans, for example.I have more feature requests to add when I'm on a laptop. I may be able to implement some myself, but I wanted to just get them out of my head first :)
[-]Feature request: C# 8 nullable refernece type support[/-][+]Feature request: C# 8 nullable reference type support[/+]danielmarbach commentedon Jun 30, 2019
Not sure I have a feasible way of implementing this without considerably revamping how the code currently works. The problem is that the current code turns everything into a CodeDom and then writes that into a string writer. So in order to pretty print the types and things annotated with
NullableAttributeI would need to do some intensive string replacing logic that covers all the special cases. If you have a good idea on how to achieve this without redesigning the whole ApiGenerator I'm all ears.jskeet commentedon Jun 30, 2019
I'll see if I can find some time to clone the repo and experiment - but that may well not lead to anything concrete, unfortunately.
sungam3r commentedon Aug 12, 2019
Generally good idea but it seems to me that it will be better to wait NET Core 3.0 final release to work with the final design of these attributes.
jnm2 commentedon Oct 14, 2019
I have a similar project (needing to be updated for NRTs) which does all the code generation from a domain model directly to TextWriter: https://github.com/jnm2/ApiContractGenerator/blob/v1.0.0/src/ApiContractGenerator/CSharpTextFormatter.cs
Maybe some of that could be usable, since the approach will have to be similar?
sungam3r commentedon Oct 14, 2019
I have conflicting feelings about this change. On the one hand, it seems that the proposal is really good. On the other hand, the current way of representing this information through attributes seems to be cleaner.
jskeet commentedon Oct 14, 2019
@sungam3r: I'm not sure in what way it's "cleaner" - it's certainly much harder to read in terms of the attribute form.
jnm2 commentedon Oct 14, 2019
The compression scheme for the byte array passed to NullableAttribute for things with nested nullability is not something I'm capable of mentally unwinding, either.
sungam3r commentedon Oct 14, 2019
@jskeet This means that we will have to do all the dirty work of reversing the conversion of type information from attributes — decompression, move bits around, matching, etc. All to solve the inverse problem of the compiler.
jskeet commentedon Oct 14, 2019
@sungam3r: Yes - but code can do that much more reliably than humans can.
jnm2 commentedon Oct 14, 2019
Part of the purpose of the text file is to be human-reviewable. It's hard to do that effectively if you don't know what you're looking at.
sungam3r commentedon Oct 14, 2019
It's all clear. We can say that these attributes are special, although they are only attributes. On the other hand, someone may want to ignore these attributes. Now it is possible to do since code does not interpret them in a special way.
jnm2 commentedon Oct 14, 2019
I don't think anyone will want to ignore them any more than they'd want to ignore
[TupleElementNames(...)]etc (which should also be decoded and written using proper C# syntax). It's API stuff that you are shipping to the world; you should not be able to opt out of seeing what you are doing.59 remaining items
danielmarbach commentedon Nov 1, 2019
jnm2 commentedon Nov 1, 2019
I tried it with Shouldly again. No errors!
System.Void?is shown wherevoidused to be before:Sometimes
voidis still shown properly even when one of the parameters is nullable.One more problem. Invalid attribute syntax (
?is not allowed):Everything else looks perfect! Let me know if you need repro code.
sungam3r commentedon Nov 1, 2019
I could not reproduce both situations. Tests are green.
jnm2 commentedon Nov 1, 2019
@sungam3r My guess is that both parameters will need to be
object?rather thanobject. I'll work on repro code.jnm2 commentedon Nov 1, 2019
I can repro against commit
aacbc4b 2019-11-01 | fix recursionwith this as the only source file:Output from
ApiGenerator.GeneratePublicApi:Also against commit
677fd84 2019-11-02 | tests.More instances I found:
jnm2 commentedon Nov 1, 2019
Repro code for the attribute syntax against commit
677fd84 2019-11-02 | tests:Produces:
Here's another instance I ran across:
jnm2 commentedon Nov 2, 2019
I ran commit
677fd84 2019-11-02 | testsagainst the entirety of https://www.nuget.org/packages/Microsoft.NETCore.App.Ref/3.0.0 (151 assemblies, 22 annotated) and both searched for all nullability syntax and visually scanned the files. Nothing looks wrong to me besides what I've already reported. There was some good variety.sungam3r commentedon Nov 2, 2019
Fixed both.
jnm2 commentedon Nov 2, 2019
Tried c5db6cc on Shouldly and https://www.nuget.org/packages/Microsoft.NETCore.App.Ref/3.0.0, all the nullability changes look perfect that I can see!
I noticed a new thing which is actually more of a problem than the encoded
NullableAttributeappearing. The[NotNull],[MaybeNullWhen(...)],[DoesNotReturn]etc attributes are not showing up at all. This is a separate problem and I'll open a new issue once I know more.jnm2 commentedon Nov 2, 2019
The issue is that internal attributes aren't shown. Anyone working with nullable reference types on target frameworks other than netcoreapp3.0+ or netstandard2.1+ will need #117.
[-]Feature request: C# 8 nullable reference type support[/-][+]C# 8 nullable reference type support[/+]sungam3r commentedon Nov 2, 2019
@jnm2 So this is not the end of the story :(
jnm2 commentedon Nov 2, 2019
No, but the implementation for #117 will not be related at all to the work in this thread and I think it will be dramatically easier. You already have logic to show or hide attributes, so we augment that by checking against a list of full attribute type names that must never be hidden.