dotnet / dotnet/dotnet-api-docs
System.Security.AccessControl.DirectoryObjectSecurity.GetAccessRules documentation incorrect for all versions of all SDKs
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
### 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:
https://github.com/dotnet/dotnet-api-docs/blob/32ba3e84f3931d4e1d306b8f6c6f20fe200c5e9e/xml/System.Security.AccessControl/DirectoryObjectSecurity.xml#L325-L376
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 `targetType`[parameter documentation](https://github.com/dotnet/dotnet-api-docs/blob/32ba3e84f3931d4e1d306b8f6c6f20fe200c5e9e/xml/System.Security.AccessControl/DirectoryObjectSecurity.xml#L371) 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`](https://github.com/dotnet/dotnet-api-docs/blob/32ba3e84f3931d4e1d306b8f6c6f20fe200c5e9e/xml/System.Security.AccessControl/DirectoryObjectSecurity.xml#L364) (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 to use for the identities in the returned rules.`"
* [It is an overload of a method that appears on its ultimate base type](https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.commonobjectsecurity.getaccessrules?view=netframework-2.0), 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](https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.directoryobjectsecurity.getaccessrules?view=netframework-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.
Contributor guide
Assessment
This issue has not been assessed yet.