System.Security.AccessControl.DirectoryObjectSecurity.GetAccessRules documentation incorrect for all versions of all SDKs

[dodexahedron]

Describe the issue or suggestion

For the article https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.directoryobjectsecurity.getaccessrules

Which comes from here:

dotnet-api-docs/xml/System.Security.AccessControl/DirectoryObjectSecurity.xml

Lines 325 to 376 in 32ba3e8

	<Member MemberName="GetAccessRules">
	<MemberSignature Language="C#" Value="public System.Security.AccessControl.AuthorizationRuleCollection GetAccessRules (bool includeExplicit, bool includeInherited, Type targetType);" />
	<MemberSignature Language="ILAsm" Value=".method public hidebysig instance class System.Security.AccessControl.AuthorizationRuleCollection GetAccessRules(bool includeExplicit, bool includeInherited, class System.Type targetType) cil managed" />
	<MemberSignature Language="DocId" Value="M:System.Security.AccessControl.DirectoryObjectSecurity.GetAccessRules(System.Boolean,System.Boolean,System.Type)" />
	<MemberSignature Language="VB.NET" Value="Public Function GetAccessRules (includeExplicit As Boolean, includeInherited As Boolean, targetType As Type) As AuthorizationRuleCollection" />
	<MemberSignature Language="F#" Value="member this.GetAccessRules : bool * bool * Type -&gt; System.Security.AccessControl.AuthorizationRuleCollection" Usage="directoryObjectSecurity.GetAccessRules (includeExplicit, includeInherited, targetType)" />
	<MemberSignature Language="C++ CLI" Value="public:&#xA; System::Security::AccessControl::AuthorizationRuleCollection ^ GetAccessRules(bool includeExplicit, bool includeInherited, Type ^ targetType);" />
	<MemberType>Method</MemberType>
	<AssemblyInfo>
	<AssemblyName>System.IO.FileSystem.AccessControl</AssemblyName>
	<AssemblyVersion>4.0.0.0</AssemblyVersion>
	<AssemblyVersion>4.0.4.0</AssemblyVersion>
	<AssemblyVersion>4.0.5.0</AssemblyVersion>
	<AssemblyVersion>5.0.0.0</AssemblyVersion>
	<AssemblyVersion>6.0.0.0</AssemblyVersion>
	<AssemblyVersion>7.0.0.0</AssemblyVersion>
	<AssemblyVersion>8.0.0.0</AssemblyVersion>
	<AssemblyVersion>9.0.0.0</AssemblyVersion>
	<AssemblyVersion>10.0.0.0</AssemblyVersion>
	<AssemblyVersion>11.0.0.0</AssemblyVersion>
	</AssemblyInfo>
	<AssemblyInfo>
	<AssemblyName>mscorlib</AssemblyName>
	<AssemblyVersion>2.0.0.0</AssemblyVersion>
	<AssemblyVersion>2.0.5.0</AssemblyVersion>
	<AssemblyVersion>4.0.0.0</AssemblyVersion>
	</AssemblyInfo>
	<Attributes>
	<Attribute FrameworkAlternate="netframework-4.0">
	<AttributeName Language="C#">[System.Security.SecuritySafeCritical]</AttributeName>
	<AttributeName Language="F#">[&lt;System.Security.SecuritySafeCritical&gt;]</AttributeName>
	</Attribute>
	</Attributes>
	<ReturnValue>
	<ReturnType>System.Security.AccessControl.AuthorizationRuleCollection</ReturnType>
	</ReturnValue>
	<Parameters>
	<Parameter Name="includeExplicit" Type="System.Boolean" />
	<Parameter Name="includeInherited" Type="System.Boolean" />
	<Parameter Name="targetType" Type="System.Type" />
	</Parameters>
	<Docs>
	<param name="includeExplicit">
	<see langword="true" /> to include access rules explicitly set for the object.</param>
	<param name="includeInherited">
	<see langword="true" /> to include inherited access rules.</param>
	<param name="targetType">The security identifier for which to retrieve access rules. This must be an object that can be cast as a <see cref="T:System.Security.Principal.SecurityIdentifier" /> object.</param>
	<summary>Gets a collection of the access rules associated with the specified security identifier.</summary>
	<returns>The collection of access rules associated with the specified <see cref="T:System.Security.Principal.SecurityIdentifier" /> object.</returns>
	<remarks>To be added.</remarks>
	</Docs>
	</Member>

There are multiple issues that make the article unhelpful.

Here are some I identified, from most important to least important:

1. (Just plain incorrect and unhelpful, requiring digging into ) The targetTypeparameter documentation refers to it as if it were some specific instance of an object. The actual purpose of it is to tell it how to interpret the identities in the rules it returns. It is a Type (and really should just be a type parameter on the method, but that's out of scope for a doc fix).
   • A better description might be something along the lines of: "A type deriving from <see cref="System.Security.Principal.IdentityReference" /> to use for the identities in the returned rules."
   • It is an overload of a method that appears on its ultimate base type, which had better, though still clumsy wording.
     • The overload on the type for this article has always had the incorrect wording, since it first appeared in .net framework 2.0, and is the same for framework and .net, on all versions since framework 2.0.
     • It should probably be fixed for all versions of all frameworks, since it has always been wrong for this overload.
2. (Not clear) The summary should be re-worded to indicate it is operating on the ActiveDirectorySecurity object it was called on, rather than referring to a SID. Even though that ultimately is true, it is an implementation detail and the object may not have been created by explicitly using a SID in the first place, so it is unclear and potentially confusing.
3. (Not clear) Same comment for the returns element.
4. (Absent but non-critical) Some remarks explaining the what and why of this method would also be nice, but that's just a nice-to-have.

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-security, @vcsjones