@_documentation now takes arguments 'visibility' and 'metadata'

Author: QuietMisdreavus

docs/ReferenceGuides/UnderscoredAttributes.md

@@ -117,20 +117,26 @@ extension Text {
 }
 ```
 
-## `@_documentation(...)`
-
-Adds a "documentation category" to the given symbol. The identifier in the
-attribute is added to the symbol graph in the `"category"` field of the symbol.
-
-There are two special-case categories: `underscored` will treat the given symbol
-as having an underscored name regardless of its actual name, effectively marking
-it as `internal`. Conversely, the `ignoreUnderscored` category will do the
-opposite: A symbol with this category will appear in symbol graphs with its
-original visibility, regardless of whether it has an underscored name.
-
-`@_documentation(underscored)` can also be applied to `@_exported import`
-statements to treat the re-exported symbols as `internal`, dropping them from
-public symbol graphs.
+## `@_documentation(metadata: ...)`
+
+Adds "documentation metadata" to the symbol. The identifier in the attribute is
+added to the symbol graph in the `"metadata"` field of the symbol. This can be
+used to add an arbitrary grouping or other indicator to symbols for use in
+documentation.
+
+## `@_documentation(visibility: ...)`
+
+Forces the symbol to be treated as the given access level when checking
+visibility. This can be used to, for example, force a symbol with an underscored
+name to appear in `public` symbol graphs, or treat an otherwise-`public` symbol
+as being `internal` or `private` for the purposes of documentation, to hide it
+from `public` docs.
+
+This can also be applied to `@_exported import` statements to only include the
+imported symbols in symbol graphs with the given minimum access level. For
+example, applying `@_documentation(visibility: internal)` to an `@_exported
+import` statement will hide the imported symbols from `public` symbol graphs and
+documentation, but show them on `internal` symbol graphs and documentation.
 
 ## `@_dynamicReplacement(for: targetFunc(label:))`
 

include/swift/AST/Attr.def

@@ -746,9 +746,9 @@ SIMPLE_DECL_ATTR(_alwaysEmitConformanceMetadata, AlwaysEmitConformanceMetadata,
   132)
 
 DECL_ATTR(_documentation, Documentation,
-  OnAnyDecl |
+  OnAnyDecl | UserInaccessible |
   APIBreakingToAdd | APIStableToRemove | ABIStableToAdd | ABIStableToRemove,
-  132)
+  133)
 
 // If you're adding a new underscored attribute here, please document it in
 // docs/ReferenceGuides/UnderscoredAttributes.md.

include/swift/AST/Attr.h

@@ -2232,15 +2232,16 @@ class BackDeployAttr: public DeclAttribute {
 class DocumentationAttr: public DeclAttribute {
 public:
   DocumentationAttr(SourceLoc AtLoc, SourceRange Range,
-                    StringRef Category,
+                    StringRef Metadata, Optional<AccessLevel> Visibility,
                     bool Implicit)
   : DeclAttribute(DAK_Documentation, AtLoc, Range, Implicit),
-    Category(Category) {}
+    Metadata(Metadata), Visibility(Visibility) {}
 
-  DocumentationAttr(StringRef Category, bool Implicit)
-  : DocumentationAttr(SourceLoc(), SourceRange(), Category, Implicit) {}
+  DocumentationAttr(StringRef Metadata, Optional<AccessLevel> Visibility, bool Implicit)
+  : DocumentationAttr(SourceLoc(), SourceRange(), Metadata, Visibility, Implicit) {}
 
-  const StringRef Category;
+  const StringRef Metadata;
+  const Optional<AccessLevel> Visibility;
 
   static bool classof(const DeclAttribute *DA) {
     return DA->getKind() == DAK_Documentation;

include/swift/AST/DiagnosticsParse.def

@@ -1464,9 +1464,6 @@ ERROR(attr_expected_string_literal,none,
 ERROR(attr_expected_integer_literal,none,
 "expected integer literal in '%0' attribute", (StringRef))
 
-ERROR(attr_expected_identifier,none,
-"expected identifier in '%0' attribute", (StringRef))
-
 ERROR(attr_expected_option_such_as,none,
       "expected '%0' option such as '%1'", (StringRef, StringRef))
 
@@ -1765,6 +1762,27 @@ WARNING(warn_attr_unsafe_removed,none,
         "'%0' attribute has been removed in favor of @preconcurrency",
         (StringRef))
 
+// _documentation
+ERROR(documentation_attr_expected_argument,none,
+      "@_documentation attribute expected 'visibility' or 'metadata' argument",
+      ())
+ERROR(documentation_attr_unknown_argument,none,
+      "unknown argument '%0', expected 'visibility' or 'metadata'",
+      (StringRef))
+ERROR(documentation_attr_expected_access_level,none,
+      "@_documentation attribute's 'visibility' argument expected an access level",
+      ())
+ERROR(documentation_attr_unknown_access_level,none,
+      "unknown visibility '%0', expected an access level keyword",
+      (StringRef))
+ERROR(documentation_attr_duplicate_visibility,none,
+      "cannot give more than one visibility to the same item", ())
+ERROR(documentation_attr_metadata_expected_identifier,none,
+      "@_documentation attribute's 'metadata' argument expected a plain identifier",
+      ())
+ERROR(documentation_attr_duplicate_metadata,none,
+      "cannot give more than one metadata argument to the same item", ())
+
 //------------------------------------------------------------------------------
 // MARK: Generics parsing diagnostics
 //------------------------------------------------------------------------------

include/swift/AST/Import.h

@@ -19,6 +19,7 @@
 #ifndef SWIFT_IMPORT_H
 #define SWIFT_IMPORT_H
 
+#include "swift/AST/AttrKind.h"
 #include "swift/AST/Identifier.h"
 #include "swift/Basic/Located.h"
 #include "swift/Basic/OptionSet.h"
@@ -84,10 +85,6 @@ enum class ImportFlags {
   /// concurrency.
   Preconcurrency = 0x20,
 
-  /// The module is being exported, but its contents should not appear in a
-  /// symbol graph.
-  NoDoc = 0x40,
-
   /// Used for DenseMap.
   Reserved = 0x80
 };
@@ -574,13 +571,18 @@ struct AttributedImport {
   /// is the source range covering the annotation.
   SourceRange preconcurrencyRange;
 
+  /// If the import declaration has a `@_documentation(visibility: <access>)`
+  /// attribute, this is the given access level.
+  Optional<AccessLevel> docVisibility;
+
   AttributedImport(ModuleInfo module, SourceLoc importLoc = SourceLoc(),
                    ImportOptions options = ImportOptions(),
                    StringRef filename = {}, ArrayRef<Identifier> spiGroups = {},
-                   SourceRange preconcurrencyRange = {})
+                   SourceRange preconcurrencyRange = {},
+                   Optional<AccessLevel> docVisibility = None)
       : module(module), importLoc(importLoc), options(options),
         sourceFileArg(filename), spiGroups(spiGroups),
-        preconcurrencyRange(preconcurrencyRange) {
+        preconcurrencyRange(preconcurrencyRange), docVisibility(docVisibility) {
     assert(!(options.contains(ImportFlags::Exported) &&
              options.contains(ImportFlags::ImplementationOnly)) ||
            options.contains(ImportFlags::Reserved));
@@ -590,14 +592,15 @@ struct AttributedImport {
   AttributedImport(ModuleInfo module, AttributedImport<OtherModuleInfo> other)
     : AttributedImport(module, other.importLoc, other.options,
                        other.sourceFileArg, other.spiGroups,
-                       other.preconcurrencyRange) { }
+                       other.preconcurrencyRange, other.docVisibility) { }
 
   friend bool operator==(const AttributedImport<ModuleInfo> &lhs,
                          const AttributedImport<ModuleInfo> &rhs) {
     return lhs.module == rhs.module &&
            lhs.options.toRaw() == rhs.options.toRaw() &&
            lhs.sourceFileArg == rhs.sourceFileArg &&
-           lhs.spiGroups == rhs.spiGroups;
+           lhs.spiGroups == rhs.spiGroups &&
+           lhs.docVisibility == rhs.docVisibility;
   }
 
   AttributedImport<ImportedModule> getLoaded(ModuleDecl *loadedModule) const {
@@ -749,14 +752,14 @@ struct DenseMapInfo<swift::AttributedImport<ModuleInfo>> {
                             SourceLocDMI::getEmptyKey(),
                             ImportOptionsDMI::getEmptyKey(),
                             StringRefDMI::getEmptyKey(),
-                            {});
+                            {}, {}, None);
   }
   static inline AttributedImport getTombstoneKey() {
     return AttributedImport(ModuleInfoDMI::getTombstoneKey(),
                             SourceLocDMI::getEmptyKey(),
                             ImportOptionsDMI::getTombstoneKey(),
                             StringRefDMI::getTombstoneKey(),
-                            {});
+                            {}, {}, None);
   }
   static inline unsigned getHashValue(const AttributedImport &import) {
     return detail::combineHashValue(
@@ -770,7 +773,8 @@ struct DenseMapInfo<swift::AttributedImport<ModuleInfo>> {
     return ModuleInfoDMI::isEqual(a.module, b.module) &&
            ImportOptionsDMI::isEqual(a.options, b.options) &&
            StringRefDMI::isEqual(a.sourceFileArg, b.sourceFileArg) &&
-           a.spiGroups == b.spiGroups;
+           a.spiGroups == b.spiGroups &&
+           a.docVisibility == b.docVisibility;
   }
 };
 }

include/swift/AST/Module.h

@@ -952,7 +952,7 @@ inline SourceLoc extractNearestSourceLoc(const ModuleDecl *mod) {
 void collectParsedExportedImports(const ModuleDecl *M,
                                   SmallPtrSetImpl<ModuleDecl *> &Imports,
                                   llvm::SmallDenseMap<ModuleDecl *, SmallPtrSet<Decl *, 4>, 4> &QualifiedImports,
-                                  bool DropNoDoc = false);
+                                  llvm::function_ref<bool(AttributedImport<ImportedModule>)> includeImport = nullptr);
 
 } // end namespace swift
 

include/swift/Parse/Parser.h

@@ -1098,6 +1098,14 @@ class Parser {
   bool parseBackDeployAttribute(DeclAttributes &Attributes, StringRef AttrName,
                                 SourceLoc AtLoc, SourceLoc Loc);
 
+  /// Parse the @_documentation attribute.
+  ParserResult<DocumentationAttr> parseDocumentationAttribute(SourceLoc AtLoc,
+                                                              SourceLoc Loc);
+
+  /// Parse a single argument from a @_documentation attribute.
+  bool parseDocumentationAttributeArgument(Optional<StringRef> &Metadata,
+                                           Optional<AccessLevel> &Visibility);
+
   /// Parse a specific attribute.
   ParserStatus parseDeclAttribute(DeclAttributes &Attributes, SourceLoc AtLoc,
                                   PatternBindingInitializer *&initContext,

include/swift/SymbolGraphGen/DocumentationCategory.h

@@ -15,25 +15,31 @@
 
 #include "swift/AST/Decl.h"
 
+#include "llvm/Support/Compiler.h"
+
 namespace swift {
 namespace symbolgraphgen {
 
-static StringRef documentationCategoryForDecl(const Decl *D) {
+LLVM_ATTRIBUTE_USED
+static StringRef documentationMetadataForDecl(const Decl *D) {
   if (!D) return {};
 
   if (const auto *DC = D->getAttrs().getAttribute<DocumentationAttr>()) {
-    return DC->Category;
+    return DC->Metadata;
   }
 
   return {};
 }
 
-static bool isUnderscoredDocumentationCategory(const Decl *D) {
-  return documentationCategoryForDecl(D) == "underscored";
-}
+LLVM_ATTRIBUTE_USED
+static Optional<AccessLevel> documentationVisibilityForDecl(const Decl *D) {
+  if (!D) return None;
+
+  if (const auto *DC = D->getAttrs().getAttribute<DocumentationAttr>()) {
+    return DC->Visibility;
+  }
 
-static bool isIgnoreUnderscoredDocumentationCategory(const Decl *D) {
-  return documentationCategoryForDecl(D) == "ignoreUnderscored";
+  return None;
 }
 
 } // namespace symbolgraphgen

lib/AST/Module.cpp

@@ -795,13 +795,13 @@ bool ModuleDecl::shouldCollectDisplayDecls() const {
 void swift::collectParsedExportedImports(const ModuleDecl *M,
                                          SmallPtrSetImpl<ModuleDecl *> &Imports,
                                          llvm::SmallDenseMap<ModuleDecl *, SmallPtrSet<Decl *, 4>, 4> &QualifiedImports,
-                                         bool DropNoDoc) {
+                                         llvm::function_ref<bool(AttributedImport<ImportedModule>)> includeImport) {
   for (const FileUnit *file : M->getFiles()) {
     if (const SourceFile *source = dyn_cast<SourceFile>(file)) {
       if (source->hasImports()) {
         for (auto import : source->getImports()) {
           if (import.options.contains(ImportFlags::Exported) &&
-              !(DropNoDoc && import.options.contains(ImportFlags::NoDoc)) &&
+              (!includeImport || includeImport(import)) &&
               import.module.importedModule->shouldCollectDisplayDecls()) {
             auto *TheModule = import.module.importedModule;
 

lib/AST/TypeCheckRequests.cpp

@@ -1459,8 +1459,6 @@ void swift::simple_display(llvm::raw_ostream &out,
 
   if (import.options.contains(ImportFlags::Exported))
     out << " exported";
-  if (import.options.contains(ImportFlags::NoDoc))
-    out << " nodoc";
   if (import.options.contains(ImportFlags::Testable))
     out << " testable";
   if (import.options.contains(ImportFlags::ImplementationOnly))