rename @_nodoc to @_documentation(...)

Author: QuietMisdreavus

docs/ReferenceGuides/UnderscoredAttributes.md

@@ -117,6 +117,20 @@ extension Text {
 }
 ```
 
+## `@_documentation(...)`
+
+Adds a "documentation category" to the given 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.
+
 ## `@_dynamicReplacement(for: targetFunc(label:))`
 
 Marks a function as the dynamic replacement for another `dynamic` function.
@@ -482,16 +496,6 @@ Fun fact: Rust has a very similar concept called
 including one called `Send`,
 which inspired the design of `Sendable`.
 
-## `@_nodoc`
-
-Indicates that a declaration should not be included in symbol graphs. Symbols
-marked with this attribute are treated as if they were given an underscored
-name, meaning they are still included in a symbol graph with a "minimum access
-level" of `internal` or lower.
-
-This attribute can also be attached to `@_exported import` statements to prevent
-symbols imported with this statement from appearing in symbol graphs.
-
 ## `@_nonEphemeral`
 
 Marks a function parameter that cannot accept a temporary pointer produced from

include/swift/AST/Attr.def

@@ -741,7 +741,7 @@ SIMPLE_DECL_ATTR(_moveOnly, MoveOnly,
   ABIBreakingToAdd | ABIBreakingToRemove | APIBreakingToAdd | APIBreakingToRemove,
   131)
 
-SIMPLE_DECL_ATTR(_nodoc, NoDoc,
+DECL_ATTR(_documentation, Documentation,
   OnAnyDecl |
   APIBreakingToAdd | APIStableToRemove | ABIStableToAdd | ABIStableToRemove,
   132)

include/swift/AST/Attr.h

@@ -2226,6 +2226,27 @@ class BackDeployAttr: public DeclAttribute {
   }
 };
 
+/// The `@_documentation(...)` attribute, used to note a "category" for a
+/// symbol to be associated with, with special cases for forcing a symbol to be
+/// hidden or visible.
+class DocumentationAttr: public DeclAttribute {
+public:
+  DocumentationAttr(SourceLoc AtLoc, SourceRange Range,
+                    StringRef Category,
+                    bool Implicit)
+  : DeclAttribute(DAK_Documentation, AtLoc, Range, Implicit),
+    Category(Category) {}
+
+  DocumentationAttr(StringRef Category, bool Implicit)
+  : DocumentationAttr(SourceLoc(), SourceRange(), Category, Implicit) {}
+
+  const StringRef Category;
+
+  static bool classof(const DeclAttribute *DA) {
+    return DA->getKind() == DAK_Documentation;
+  }
+};
+
 
 /// Attributes that may be applied to declarations.
 class DeclAttributes {

include/swift/AST/DiagnosticsParse.def

@@ -1464,6 +1464,9 @@ 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))
 

include/swift/SymbolGraphGen/DocumentationCategory.h

@@ -0,0 +1,42 @@
+//===--- DocumentationCategory.h - Accessors for @_documentation ----------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef SWIFT_SYMBOLGRAPHGEN_DOCUMENTATIONCATEGORY_H
+#define SWIFT_SYMBOLGRAPHGEN_DOCUMENTATIONCATEGORY_H
+
+#include "swift/AST/Decl.h"
+
+namespace swift {
+namespace symbolgraphgen {
+
+static StringRef documentationCategoryForDecl(const Decl *D) {
+  if (!D) return {};
+
+  if (const auto *DC = D->getAttrs().getAttribute<DocumentationAttr>()) {
+    return DC->Category;
+  }
+
+  return {};
+}
+
+static bool isUnderscoredDocumentationCategory(const Decl *D) {
+  return documentationCategoryForDecl(D) == "underscored";
+}
+
+static bool isIgnoreUnderscoredDocumentationCategory(const Decl *D) {
+  return documentationCategoryForDecl(D) == "ignoreUnderscored";
+}
+
+} // namespace symbolgraphgen
+} // namespace swift
+
+#endif // SWIFT_SYMBOLGRAPHGEN_DOCUMENTATIONCATEGORY_H

lib/AST/Attr.cpp

@@ -1440,6 +1440,8 @@ StringRef DeclAttribute::getAttrName() const {
     return "_unavailableFromAsync";
   case DAK_BackDeploy:
     return "_backDeploy";
+  case DAK_Documentation:
+    return "_documentation";
   }
   llvm_unreachable("bad DeclAttrKind");
 }

lib/Parse/ParseDecl.cpp

@@ -2980,6 +2980,33 @@ bool Parser::parseNewDeclAttribute(DeclAttributes &Attributes, SourceLoc AtLoc,
       return false;
     break;
   }
+  case DAK_Documentation: {
+    if (!consumeIf(tok::l_paren)) {
+      diagnose(Loc, diag::attr_expected_lparen, AttrName,
+               DeclAttribute::isDeclModifier(DK));
+      return false;
+    }
+
+    if (Tok.isNot(tok::identifier)) {
+      diagnose(Loc, diag::attr_expected_identifier, AttrName);
+      return false;
+    }
+
+    auto category = Tok.getText();
+
+    consumeToken(tok::identifier);
+
+    auto range = SourceRange(Loc, Tok.getRange().getStart());
+
+    if (!consumeIf(tok::r_paren)) {
+      diagnose(Loc, diag::attr_expected_rparen, AttrName,
+               DeclAttribute::isDeclModifier(DK));
+      return false;
+    }
+
+    Attributes.add(new (Context) DocumentationAttr(AtLoc, range, category, false));
+    break;
+  }
   }
 
   if (DuplicateAttribute) {

lib/Sema/ImportResolution.cpp

@@ -28,6 +28,7 @@
 #include "swift/ClangImporter/ClangModule.h"
 #include "swift/Parse/Parser.h"
 #include "swift/Subsystems.h"
+#include "swift/SymbolGraphGen/DocumentationCategory.h"
 #include "clang/Basic/Module.h"
 #include "llvm/ADT/DenseMap.h"
 #include "llvm/ADT/TinyPtrVector.h"
@@ -530,7 +531,7 @@ UnboundImport::UnboundImport(ImportDecl *ID)
   if (ID->isExported())
     import.options |= ImportFlags::Exported;
 
-  if (ID->getAttrs().hasAttribute<NoDocAttr>())
+  if (swift::symbolgraphgen::isUnderscoredDocumentationCategory(ID))
     import.options |= ImportFlags::NoDoc;
 
   if (ID->getAttrs().hasAttribute<TestableAttr>())

lib/Sema/TypeCheckAttr.cpp

@@ -157,7 +157,7 @@ class AttributeChecker : public AttributeVisitor<AttributeChecker> {
   IGNORED_ATTR(Isolated)
   IGNORED_ATTR(Preconcurrency)
   IGNORED_ATTR(BackDeploy)
-  IGNORED_ATTR(NoDoc)
+  IGNORED_ATTR(Documentation)
 #undef IGNORED_ATTR
 
   void visitAlignmentAttr(AlignmentAttr *attr) {

lib/Sema/TypeCheckDeclOverride.cpp

@@ -1491,6 +1491,7 @@ namespace  {
     UNINTERESTING_ATTR(Borrowed)
     UNINTERESTING_ATTR(CDecl)
     UNINTERESTING_ATTR(Consuming)
+    UNINTERESTING_ATTR(Documentation)
     UNINTERESTING_ATTR(Dynamic)
     UNINTERESTING_ATTR(DynamicCallable)
     UNINTERESTING_ATTR(DynamicMemberLookup)
@@ -1519,7 +1520,6 @@ namespace  {
     UNINTERESTING_ATTR(Lazy)
     UNINTERESTING_ATTR(LLDBDebuggerFunction)
     UNINTERESTING_ATTR(Mutating)
-    UNINTERESTING_ATTR(NoDoc)
     UNINTERESTING_ATTR(NonMutating)
     UNINTERESTING_ATTR(NonEphemeral)
     UNINTERESTING_ATTR(NonObjC)

lib/Serialization/Deserialization.cpp

@@ -5003,6 +5003,16 @@ llvm::Error DeclDeserializer::deserializeDeclCommon() {
         break;
       }
 
+      case decls_block::Documentation_DECL_ATTR: {
+        bool isImplicit;
+        uint64_t CategoryID;
+        serialization::decls_block::DocumentationDeclAttrLayout::readRecord(
+            scratch, isImplicit, CategoryID);
+        StringRef CategoryText = MF.getIdentifierText(CategoryID);
+        Attr = new (ctx) DocumentationAttr(CategoryText, isImplicit);
+        break;
+      }
+
 #define SIMPLE_DECL_ATTR(NAME, CLASS, ...) \
       case decls_block::CLASS##_DECL_ATTR: { \
         bool isImplicit; \

lib/Serialization/ModuleFormat.h

@@ -2096,6 +2096,12 @@ namespace decls_block {
     BCVBR<5>        // platform
   >;
 
+  using DocumentationDeclAttrLayout = BCRecordLayout<
+    Documentation_DECL_ATTR,
+    BCFixed<1>,         // implicit flag
+    IdentifierIDField   // category name
+  >;
+
 #undef SYNTAX_SUGAR_TYPE_LAYOUT
 #undef TYPE_LAYOUT
 #undef TYPE_LAYOUT_IMPL

lib/Serialization/Serialization.cpp

@@ -2844,6 +2844,15 @@ class Serializer::DeclSerializer : public DeclVisitor<DeclSerializer> {
           theAttr->Message);
       return;
     }
+
+    case DAK_Documentation: {
+      auto *theAttr = cast<DocumentationAttr>(DA);
+      auto abbrCode = S.DeclTypeAbbrCodes[DocumentationDeclAttrLayout::Code];
+      auto categoryIDPair = S.addUniquedString(theAttr->Category);
+      DocumentationDeclAttrLayout::emitRecord(
+          S.Out, S.ScratchRecord, abbrCode, theAttr->isImplicit(), categoryIDPair.second);
+      return;
+    }
     }
   }
 

lib/SymbolGraphGen/SymbolGraph.cpp

@@ -18,6 +18,7 @@
 #include "swift/AST/USRGeneration.h"
 #include "swift/Basic/Version.h"
 #include "swift/Sema/IDETypeChecking.h"
+#include "swift/SymbolGraphGen/DocumentationCategory.h"
 
 #include "DeclarationFragmentPrinter.h"
 #include "FormatVersion.h"
@@ -582,7 +583,8 @@ bool SymbolGraph::isImplicitlyPrivate(const Decl *D,
   }
 
   // Don't record effectively internal declarations if specified
-  if (D->hasUnderscoredNaming() || D->getAttrs().hasAttribute<NoDocAttr>()) {
+  if (isUnderscoredDocumentationCategory(D) ||
+      (D->hasUnderscoredNaming() && !isIgnoreUnderscoredDocumentationCategory(D))) {
     // Some implicit decls from Clang with underscored names sneak in, so throw those out
     if (const auto *clangD = D->getClangDecl()) {
       if (clangD->isImplicit())

test/SymbolGraph/Module/NoDocExportedImport.swift renamed to test/SymbolGraph/Module/DocAttrExportedImport.swift

@@ -2,16 +2,16 @@
 // RUN: %target-swift-frontend %S/Inputs/ExportedImport/A.swift -module-name A -emit-module -emit-module-path %t/A.swiftmodule
 // RUN: %target-swift-frontend %S/Inputs/ExportedImport/B.swift -module-name B -emit-module -emit-module-path %t/B.swiftmodule
 
-// RUN: %target-swift-frontend %s -module-name NoDocExportedImport -emit-module -emit-module-path /dev/null -I %t -emit-symbol-graph -emit-symbol-graph-dir %t/
-// RUN: %FileCheck %s --input-file %t/NoDocExportedImport.symbols.json --check-prefix PUBLIC
+// RUN: %target-swift-frontend %s -module-name DocAttrExportedImport -emit-module -emit-module-path /dev/null -I %t -emit-symbol-graph -emit-symbol-graph-dir %t/
+// RUN: %FileCheck %s --input-file %t/DocAttrExportedImport.symbols.json --check-prefix PUBLIC
 // RUN: ls %t | %FileCheck %s --check-prefix FILES
 
-// RUN: %target-swift-frontend %s -module-name NoDocExportedImport -emit-module -emit-module-path /dev/null -I %t -emit-symbol-graph -emit-symbol-graph-dir %t/ -symbol-graph-minimum-access-level internal
-// RUN: %FileCheck %s --input-file %t/NoDocExportedImport.symbols.json --check-prefix INTERNAL
+// RUN: %target-swift-frontend %s -module-name DocAttrExportedImport -emit-module -emit-module-path /dev/null -I %t -emit-symbol-graph -emit-symbol-graph-dir %t/ -symbol-graph-minimum-access-level internal
+// RUN: %FileCheck %s --input-file %t/DocAttrExportedImport.symbols.json --check-prefix INTERNAL
 // RUN: ls %t | %FileCheck %s --check-prefix FILES
 
-@_nodoc @_exported import A
-@_nodoc @_exported import struct B.StructOne
+@_documentation(underscored) @_exported import A
+@_documentation(underscored) @_exported import struct B.StructOne
 
 // PUBLIC-NOT: InternalSymbolFromA
 // PUBLIC-NOT: StructTwo
@@ -26,5 +26,5 @@
 // FIXME: Symbols from `@_exported import` do not get emitted when using swift-symbolgraph-extract
 // This is tracked by https://bugs.swift.org/browse/SR-15921.
 
-// FILES-NOT: NoDocExportedImport@A.symbols.json
+// FILES-NOT: DocAttrExportedImport@A.symbols.json
 

test/SymbolGraph/Symbols/DocumentationAttr.swift

@@ -0,0 +1,47 @@
+// RUN: %empty-directory(%t)
+// RUN: %target-build-swift %s -module-name DocumentationAttr -emit-module -emit-module-path %t/
+// RUN: %target-swift-symbolgraph-extract -module-name DocumentationAttr -I %t -pretty-print -output-dir %t
+// RUN: %FileCheck %s --input-file %t/DocumentationAttr.symbols.json --check-prefix PUBLIC
+
+// RUN: %target-swift-symbolgraph-extract -module-name DocumentationAttr -I %t -pretty-print -output-dir %t -minimum-access-level internal
+// RUN: %FileCheck %s --input-file %t/DocumentationAttr.symbols.json --check-prefix INTERNAL
+
+// RUN: %target-swift-symbolgraph-extract -module-name DocumentationAttr -I %t -pretty-print -output-dir %t -minimum-access-level private
+// RUN: %FileCheck %s --input-file %t/DocumentationAttr.symbols.json --check-prefix PRIVATE
+
+// This test is a mirror of SkipsPublicUnderscore.swift, but using `@_documentation`
+// instead of underscored names.
+
+public protocol PublicProtocol {}
+
+// PUBLIC-NOT: ShouldntAppear
+// INTERNAL-DAG: ShouldntAppear
+// PRIVATE-DAG: ShouldntAppear
+
+@_documentation(underscored) public struct ShouldntAppear: PublicProtocol {
+    public struct InnerShouldntAppear {}
+}
+
+public class SomeClass {
+    // PUBLIC-NOT: internalVar
+    // INTERNAL-NOT: internalVar
+    // PRIVATE-DAG: internalVar
+    @_documentation(underscored) internal var internalVar: String = ""
+}
+
+@_documentation(underscored) public protocol ProtocolShouldntAppear {}
+
+public struct PublicStruct: ProtocolShouldntAppear {
+    @_documentation(underscored) public struct InnerShouldntAppear {}
+}
+
+// The presence of `@_documentation(ignoreUnderscored)` should cause SymbolGraphGen to include an
+// underscored enum case.
+
+// PUBLIC-DAG: _ShouldAppear
+
+public enum PublicEnum {
+    case RegularCase
+    case _ShouldntAppear
+    @_documentation(ignoreUnderscored) case _ShouldAppear
+}