Q:

On the  tag

I'm reading the C# spec about <permission> tag with this syntax:
<permission cref="member">description</permission> 

It is said that:

This tag allows the security accessibility of a member to be
  documented where cref="member" is the name of a member, while description is the description of the access to the member.

So I could argue that something like this could be valid:
/// <permission cref="foo">foo is not accessible</permission>
private void foo() {}

However in the spec there is the following example:
/// <permission cref="System.Security.PermissionSet">Everyone can 
/// access this method.</permission> 
public static void Test() { } 

If cref is the member that must be documented for the accessibility what does System.Security.PermissionSet do with it? 
Really I don't understand the spec example!!!

A:

I think that was designed to document code access security requirements of a given method\class. For example:
/// <summary>
/// Do stuff
/// </summary>
/// <permission cref="PermissionSet">Caller should have full trust</permission>
[PermissionSet(SecurityAction.LinkDemand, Name = "FullTrust")]        
public void DoStuff() {

}

Here we demand full trust permission set, and we state that explicitly in documentation of our method. Also consider this:
/// <summary>
///  Do stuff 2
/// </summary>
/// <permission cref="FileIOPermission">Caller should have unrestricted IO access</permission>
[FileIOPermission(SecurityAction.Demand, Unrestricted = true)]
public void DoStuff2() {

}

Here we demand specific FileIOPermission (not permission set), and so we state that explicitly in documentation.
This is certainly not to document accessibility (public\private) of a member - why do that at all? Accessibility is part of function\class definition and do not need to be documented.

