Should API reference keep including permission information?

[svick]

Many API reference pages include section on "security", which explains which SecurityAction is required to use them. As far as I know, using System.Security.Permissions is discouraged on .Net Framework and they are not used on .Net Core at all.

Is there a reason why this information should still be included or can it be removed wholesale?

[mairaw]

@karelz @weshaggard @terrajobst can you guys comment on this one? Thanks!

[karelz]

@bartonjs @GrabYourPitchforks will be the right experts I think.

[bartonjs]

I don't know that I would remove it from .NET Framework documentation since it still describes exceptions which can be thrown.

[svick]

@bartonjs I'm not talking about removing SecurityException from the Exceptions section, e.g.:

I'm talking about the separate Security section:

Sorry if that wasn't clear.

(These examples are from FileStream(String, FileMode).)

If you think even the Security section is still useful for .Net Framework, maybe it should be at least hidden for .Net Core?

[bartonjs]

It seems fine to remove it (and the exception-ref) from .NET Core; but I don't know it's worth the documentation shear right now. But for Framework since we should continue to document the SecurityException (because it can be thrown) we should continue to document the things that cause the SecurityException to be thrown.

I don't really have a strong opinion about keeping a separate section vs folding it into the statement (e.g. SecurityException | When thingadoo doesn't have a FileIOPermission with Read, Write, or Append (as appropriate). s/thingadoo/whatever-scope-is-relevant/.

Since that seems like it would be a fair amount of work, I don't know that It would be worth it at this time.

So, in short: It currently provides value for .NET Framework; and if the documentation is shared between NetFX and CoreFX it doesn't seem like this justifies a split (but removing it from any file which has already gone core-specific seems legit).

[mairaw]

Thanks for your input @bartonjs. Core specific classes don't have this information, so we're good on that front.
I can check with the engineering team if we could display or hide that section based on the moniker selected. /cc @dend

[rpetrusha]

We could just merge the section into the Exceptions section (and qualify it as being for the .NET Framework only). I suspect that having it in a separate Security (or Permissions) section also made it less noticeable.

[jkotas]

I have run into this when looking when looking at unrelated issue. The documentation of the required code access security permissions adds a lot of legacy clutter to the documentation.

The code access security is officially deprecated for number if years. It is documented here: https://docs.microsoft.com/en-us/dotnet/framework/misc/code-access-security . I believe it would be perfectly fine to delete the required code access security permissions from the documentation.

@mairaw I will be happy to do a global find&replace to delete this if you are ok with it. Let me know.