Add doc comments and rdars to tests

Author: elsh

include/swift/AST/AccessScope.h

@@ -85,15 +85,13 @@ class AccessScope {
     return !Value.getPointer() && Value.getInt() == AccessLimitKind::Package;
   }
 
-  /// Returns true if this scope is more restrictive than the argument scope.
-  /// This function does _not_ check if the access level is more restrictive than the argument access level.
-  /// It checks if the scope of this use site is more restrictive than the scope of the argument (decl site).
-  /// For example, the scope is FileUnit for a fileprivate decl, Module for an internal decl, and null for a public
-  /// or package decl.
-  /// \see DeclContext::isChildContextOf
+  /// Returns true if the context of this (use site) is more restrictive than
+  /// the argument context (decl site). This function does _not_ check the
+  /// restrictiveness of the access level between this and the argument. \see
+  /// AccessScope::isInContext
   bool isChildOf(AccessScope AS) const {
-    if (isInternalOrLess()) {
-      if (AS.isInternalOrLess())
+    if (isInContext()) {
+      if (AS.isInContext())
         return allowsPrivateAccess(getDeclContext(), AS.getDeclContext());
       else
         return AS.isPackage() || AS.isPublic();
@@ -105,7 +103,27 @@ class AccessScope {
     return false;
   }
 
-  bool isInternalOrLess() const { return getDeclContext() != nullptr; }
+  /// Result depends on whether it's called at a use site or a decl site:
+  ///
+  /// For example,
+  ///
+  /// ```
+  /// public func foo(_ arg: bar) {} // `bar` is a `package` decl in another
+  /// module
+  /// ```
+  ///
+  /// The meaning of \c isInContext changes whether it's at the use site or the
+  /// decl site.
+  ///
+  /// The use site of \c bar, i.e. \c foo, is "in context" (decl context is
+  /// non-null), regardless of the access level of \c foo (\c public in this
+  /// case).
+  ///
+  /// The decl site of \c bar is only "in context" if the access level of the
+  /// decl is \c internal or more restrictive. The context at the decl site is\c
+  /// FileUnit if the decl is \c fileprivate or \c private; \c ModuleDecl if \c
+  /// internal, and null if \c package or \c public.
+  bool isInContext() const { return getDeclContext() != nullptr; }
 
   /// Returns the associated access level for diagnostic purposes.
   AccessLevel accessLevelForDiagnostics() const;

test/Sema/accessibility.swift

@@ -1021,8 +1021,8 @@ public struct PublicWithInternalSettersConformPublic : PublicMutationOperations
 }
 
 public struct PublicWithPackageSettersConformPublic : PublicMutationOperations {
-  public package(set) var size = 0 // FIXME: this should error
-  public package(set) subscript (_: Int) -> Int { // FIXME: this should error
+  public package(set) var size = 0 // FIXME: rdar://104987295 this should error
+  public package(set) subscript (_: Int) -> Int { // FIXME: rdar://104987295 this should error
     get { return 42 }
     set {}
   }
@@ -1471,7 +1471,7 @@ public class DerivedFromInternalConcreteGenericComposition : InternalConcreteGen
   public func publicReq() {}
 }
 
-// FIXME: should have expected note and error 'class cannot be declared public because its superclass is internal'
+// FIXME: rdar://104987455 should have expected note and error 'class cannot be declared public because its superclass is internal'
 internal typealias InternalConcreteGenericCompositionPkg = PackageGenericClass<Int> & PackageProto
 public class DerivedFromInternalConcreteGenericCompositionPkg : InternalConcreteGenericCompositionPkg { // expected-error {{class cannot be declared public because its superclass uses a package type as a generic parameter}}
   public func packageReq() {}