Skip to content

Conversation

@gewarren
Copy link
Contributor

@gewarren gewarren commented Nov 12, 2021

This refresh includes the following key changes:

  • Exclude source generator APIs
  • Add 3 assemblies that were previously omitted (System.Numerics.Vectors.dll, System.IO.Compression.Brotli.dll, System.Formats.Cbor.dll)
  • Add System.Runtime.dll assembly from the System.Runtime.Experimental package to the extensions moniker

Build.Reason:Manual by Genevieve Warren
Build.Url:https://apidrop.visualstudio.com/Content%20CI/_build/results?buildId=264012&view=results
source_repo.branch:net6-ga
source_repo.url:https://apidrop.visualstudio.com/_git/binaries

 Build.Reason:Manual by Genevieve Warren
 Build.Url:https://apidrop.visualstudio.com/Content%20CI/_build/results?buildId=264012&view=results
 source_repo.branch:net6-ga
 source_repo.url:https://apidrop.visualstudio.com/_git/binaries
@gewarren gewarren requested review from a team as code owners November 12, 2021 18:10
@ghost ghost added the area-Meta Concerns something that extends across runtime area boundaries, for example, IDisposable. label Nov 12, 2021
@@ -54,27 +59,165 @@
<BaseTypeName>System.ValueType</BaseTypeName>
</Base>
<Interfaces>
<Interface FrameworkAlternate="dotnet-plat-ext-6.0">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These interfaces and the new members that come from them are all RequiresPreviewFeatures. Do we have something (even just displaying the attribute) to help display to users the APIs are "preview only" and not available for use in production?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we display the attribute in the syntax box at least:

image

Preview

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it also display for the methods? Like struct Int32 { int IAdditionOperators<int, int, int>.operator +(int left, int right); } ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm, it actually looks like those methods aren't visible at all: https://review.docs.microsoft.com/en-us/dotnet/api/system.int32?view=dotnet-plat-ext-6.0&branch=pr-en-us-7384

I'd expect them to be under Explicit Interface Implementations and have the RequiresPreviewFeatures attribute

Copy link
Contributor Author

@gewarren gewarren Nov 12, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like there is some work to do here then. It seems to be a problem with mdoc, because I don't see a sign of those EIIs in the ECMAXML either. I wonder if we shouldn't publish the APIs from the experimental package just yet? cc @huangmin-ms @mimisasouvanh.

I do see that for existing operators and methods that newly implement an interface method in the experimental package, at least that "Implements" information shows up, e.g.: https://review.docs.microsoft.com/en-us/dotnet/api/system.double.op_lessthan?view=dotnet-plat-ext-6.0&branch=pr-en-us-7384

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gewarren @tannergooding @mimisasouvanh the preview feature - static abstract members in interfaces is not yet supported in mdoc.

@opbld34
Copy link

opbld34 commented Nov 12, 2021

Docs Build status updates of commit 1fe83c3:

⚠️ Validation status: warnings

File Status Preview URL Details
xml/System.Reflection/CustomAttributeExtensions.xml ⚠️Warning View Details
xml/System.Reflection/RuntimeReflectionExtensions.xml ⚠️Warning View Details
xml/System.Runtime.InteropServices/CriticalHandle.xml ⚠️Warning View Details
xml/System.Runtime.InteropServices/SafeHandle.xml ⚠️Warning View Details
xml/System.Security.Policy/Evidence.xml ⚠️Warning View Details
xml/System/HashCode.xml ⚠️Warning View Details
xml/System.Threading/Timer.xml 💡Suggestion View Details
xml/FrameworksIndex/dotnet-plat-ext-6.0.xml ✅Succeeded
xml/FrameworksIndex/net-6.0.xml ✅Succeeded
xml/FrameworksIndex/windowsdesktop-6.0.xml ✅Succeeded
xml/Microsoft.Extensions.Configuration/IConfiguration.xml ✅Succeeded View
xml/Microsoft.JSInterop.Infrastructure/IJSVoidResult.xml ✅Succeeded View
xml/Microsoft.JSInterop/JSCallResultType.xml ✅Succeeded View
xml/Microsoft.Win32.SafeHandles/SafeFileHandle.xml ✅Succeeded View
xml/Microsoft.Win32.SafeHandles/SafeWaitHandle.xml ✅Succeeded View
xml/System.Buffers/MemoryHandle.xml ✅Succeeded View
xml/System.CodeDom.Compiler/GeneratedCodeAttribute.xml ✅Succeeded View
xml/System.CodeDom.Compiler/IndentedTextWriter.xml ✅Succeeded View
xml/System.Collections.Generic/IComparer`1.xml ✅Succeeded View
xml/System.Collections.Generic/IDictionary`2.xml ✅Succeeded View
xml/System.Collections.Generic/IEnumerable`1.xml ✅Succeeded View
xml/System.Collections.Generic/IEnumerator`1.xml ✅Succeeded View
xml/System.Collections.Generic/IEqualityComparer`1.xml ✅Succeeded View
xml/System.Collections.Generic/IReadOnlyDictionary`2.xml ✅Succeeded View
xml/System.Collections.Generic/IReadOnlyList`1.xml ✅Succeeded View
xml/System.Collections.Generic/KeyNotFoundException.xml ✅Succeeded View
xml/System.Collections.Generic/KeyValuePair`2.xml ✅Succeeded View
xml/System.Collections.ObjectModel/Collection`1.xml ✅Succeeded View
xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml ✅Succeeded View
xml/System.Collections/ArrayList.xml ✅Succeeded View
xml/System.Collections/Comparer.xml ✅Succeeded View
xml/System.Collections/DictionaryEntry.xml ✅Succeeded View
xml/System.Collections/Hashtable.xml ✅Succeeded View
xml/System.Collections/IComparer.xml ✅Succeeded View
xml/System.Collections/IDictionary.xml ✅Succeeded View
xml/System.Collections/IDictionaryEnumerator.xml ✅Succeeded View
xml/System.Collections/IEnumerator.xml ✅Succeeded View
xml/System.Collections/IEqualityComparer.xml ✅Succeeded View
xml/System.Collections/IHashCodeProvider.xml ✅Succeeded View
xml/System.Collections/IList.xml ✅Succeeded View
xml/System.Collections/IStructuralComparable.xml ✅Succeeded View
xml/System.Collections/IStructuralEquatable.xml ✅Succeeded View
xml/System.ComponentModel.DataAnnotations/AssociatedMetadataTypeTypeDescriptionProvider.xml ✅Succeeded View
xml/System.ComponentModel/DefaultValueAttribute.xml ✅Succeeded View
xml/System.ComponentModel/EditorBrowsableAttribute.xml ✅Succeeded View
xml/System.Configuration.Assemblies/AssemblyHashAlgorithm.xml ✅Succeeded View
xml/System.Configuration.Assemblies/AssemblyVersionCompatibility.xml ✅Succeeded View
xml/System.Diagnostics.CodeAnalysis/DynamicallyAccessedMembersAttribute.xml ✅Succeeded View
xml/System.Diagnostics.CodeAnalysis/ExcludeFromCodeCoverageAttribute.xml ✅Succeeded View
xml/System.Diagnostics.CodeAnalysis/MemberNotNullAttribute.xml ✅Succeeded View

This comment lists only the first 50 files in the pull request.

xml/System.Reflection/CustomAttributeExtensions.xml

  • Line 0, Column 0: [Warning: ECMA2Yaml_UidAssembly_NotMatched] System.Reflection.CustomAttributeExtensions's moniker windowsdesktop-5.0 can't match any assembly.

xml/System.Reflection/RuntimeReflectionExtensions.xml

  • Line 0, Column 0: [Warning: ECMA2Yaml_UidAssembly_NotMatched] System.Reflection.RuntimeReflectionExtensions's moniker windowsdesktop-5.0 can't match any assembly.

xml/System.Runtime.InteropServices/CriticalHandle.xml

  • Line 0, Column 0: [Warning: ECMA2Yaml_UidAssembly_NotMatched] System.Runtime.InteropServices.CriticalHandle's moniker netstandard-1.5 can't match any assembly.

xml/System.Runtime.InteropServices/SafeHandle.xml

  • Line 0, Column 0: [Warning: ECMA2Yaml_UidAssembly_NotMatched] System.Runtime.InteropServices.SafeHandle's moniker netstandard-1.5 can't match any assembly.

xml/System.Security.Policy/Evidence.xml

  • Line 0, Column 0: [Warning: ECMA2Yaml_UidAssembly_NotMatched] System.Security.Policy.Evidence's moniker dotnet-plat-ext-6.0 can't match any assembly.

xml/System/HashCode.xml

  • Line 0, Column 0: [Warning: ECMA2Yaml_UidAssembly_NotMatched] System.HashCode's moniker dotnet-plat-ext-3.0 can't match any assembly.
  • Line 0, Column 0: [Warning: ECMA2Yaml_UidAssembly_NotMatched] System.HashCode's moniker dotnet-plat-ext-3.1 can't match any assembly.
  • Line 0, Column 0: [Warning: ECMA2Yaml_UidAssembly_NotMatched] System.HashCode's moniker dotnet-plat-ext-5.0 can't match any assembly.

xml/System.Threading/Timer.xml

  • Line 0, Column 0: [Suggestion: disallowed-html-tag - See documentation] HTML tag 'see' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder.
  • Line 0, Column 0: [Suggestion: disallowed-html-tag - See documentation] HTML tag 'see' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder.

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

@AraHaan
Copy link
Member

AraHaan commented Nov 12, 2021

This refresh includes the following key changes:

* Exclude source generator APIs

Why? People use these apis, why not keem them documented here.

* Add assemblies for 3 assemblies where previously they were omitted (System.Numerics.Vectors.dll, System.IO.Compression.Brotli.dll, System.Formats.Cbor.dll)

Did you mean to word this as Add 3 assemblies that where previously omitted?

* Add System.Runtime.dll assembly from the System.Runtime.Experimental package to the extensions moniker

I wonder why there is no net-experimental tfm instead of needing to reference them by packages which would then always reference the experimental versions of the runtimes for .NET vNext.

@eerhardt
Copy link
Member

This refresh includes the following key changes:

* Exclude source generator APIs

Why? People use these apis, why not keem them documented here.

This means to exclude the public APIs in the library that implements the source generator itself. No one calls into the source generator library - just the compiler. External developers don't call methods on the JsonSourceGenerator class.

@gewarren
Copy link
Contributor Author

Did you mean to word this as Add 3 assemblies that where previously omitted?

Yes, I did. I've updated it, thanks.

@gewarren
Copy link
Contributor Author

gewarren commented Nov 12, 2021

Two interesting things to note for types like Char:

  • Syntax block is crowded now:

    image

  • It shows as being applicable to the .NET platform extensions moniker (this is due to the version of System.Runtime.dll that's in the System.Runtime.Experimental package). Are we okay with this? Or should I try to fix it somehow?

    image

@tannergooding
Copy link
Member

Syntax block is crowded now:

Notably, the type only directly implements:

public readonly struct Char : IComparable, IComparable<char>, IEquatable<char>, IConvertible, ISpanFormattable
#if FEATURE_GENERIC_MATH
        , IBinaryInteger<char>,
          IMinMaxValue<char>,
          IUnsignedNumber<char>
#endif // FEATURE_GENERIC_MATH

I wonder if there would be some benefit to not displaying the transitive closure in the block here and instead only showing the "top level" set of interfaces. The transitive closure could then be displayed elsewhere...

Notably, we also get:
image

Where those TSelf and TOther are actually Char. Likewise, this list is much bigger than strictly necessary. Most of the interfaces listed are "indirectly" implemented and perhaps we could have Implements and Indirectly Implements or something?

@gewarren
Copy link
Contributor Author

Closing in favor of #7387

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area-Meta Concerns something that extends across runtime area boundaries, for example, IDisposable.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants