Merge pull request #65265 from hamishknight/whats-up-doc

Author: hamishknight

include/swift/AST/ASTContext.h

@@ -1545,12 +1545,6 @@ class ASTContext final {
   Optional<ExternalSourceLocs *> getExternalSourceLocs(const Decl *D);
   void setExternalSourceLocs(const Decl *D, ExternalSourceLocs *Locs);
 
-  Optional<std::pair<RawComment, bool>> getRawComment(const Decl *D);
-  void setRawComment(const Decl *D, RawComment RC, bool FromSerialized);
-
-  Optional<StringRef> getBriefComment(const Decl *D);
-  void setBriefComment(const Decl *D, StringRef Comment);
-
   friend TypeBase;
   friend ArchetypeType;
   friend OpaqueTypeDecl;

include/swift/AST/Comment.h

@@ -93,27 +93,16 @@ class DocComment {
 };
 
 /// Get a parsed documentation comment for the declaration, if there is one.
-///
-/// \param AllowSerialized Allow loading serialized doc comment data, including
-/// comment ranges.
 DocComment *getSingleDocComment(swift::markup::MarkupContext &Context,
-                                const Decl *D, bool AllowSerialized = false);
+                                const Decl *D);
 
 /// Get the declaration that actually provides a doc comment for another.
-///
-/// \param AllowSerialized Allow loading serialized doc comment data, including
-/// comment ranges.
-const Decl *getDocCommentProvidingDecl(const Decl *D,
-                                       bool AllowSerialized = false);
+const Decl *getDocCommentProvidingDecl(const Decl *D);
 
 /// Attempt to get a doc comment from the declaration, or other inherited
 /// sources, like from base classes or protocols.
-///
-/// \param AllowSerialized Allow loading serialized doc comment data, including
-/// comment ranges.
 DocComment *getCascadingDocComment(swift::markup::MarkupContext &MC,
-                                   const Decl *D,
-                                   bool AllowSerialized = false);
+                                   const Decl *D);
 
 /// Extract comments parts from the given Markup node.
 swift::markup::CommentParts
@@ -122,6 +111,25 @@ extractCommentParts(swift::markup::MarkupContext &MC,
 
 /// Extract brief comment from \p RC, and print it to \p OS .
 void printBriefComment(RawComment RC, llvm::raw_ostream &OS);
+
+/// Describes the intended serialization target for a doc comment.
+enum class DocCommentSerializationTarget : uint8_t {
+  /// The doc comment should not be serialized.
+  None = 0,
+
+  /// The doc comment should only be serialized in the 'swiftsourceinfo'.
+  SourceInfoOnly,
+
+  /// The doc comment should be serialized in both the 'swiftdoc' and
+  /// 'swiftsourceinfo'.
+  SwiftDocAndSourceInfo,
+};
+
+/// Retrieve the expected serialization target for a documentation comment
+/// attached to the given decl.
+DocCommentSerializationTarget
+getDocCommentSerializationTargetFor(const Decl *D);
+
 } // namespace swift
 
 #endif // LLVM_SWIFT_AST_COMMENT_H

include/swift/AST/Decl.h

@@ -747,6 +747,7 @@ class alignas(1 << DeclAlignInBits) Decl : public ASTAllocated<Decl> {
   friend class IterableDeclContext;
   friend class MemberLookupTable;
   friend class DeclDeserializer;
+  friend class RawCommentRequest;
 
 private:
   llvm::PointerUnion<DeclContext *, ASTContext *> Context;
@@ -1015,16 +1016,17 @@ class alignas(1 << DeclAlignInBits) Decl : public ASTAllocated<Decl> {
   }
 
   /// \returns the unparsed comment attached to this declaration.
-  RawComment getRawComment(bool SerializedOK = false) const;
+  RawComment getRawComment() const;
 
   Optional<StringRef> getGroupName() const;
 
   Optional<StringRef> getSourceFileName() const;
 
   Optional<unsigned> getSourceOrder() const;
 
-  /// \returns the brief comment attached to this declaration.
-  StringRef getBriefComment() const;
+  /// \returns The brief comment attached to this declaration, or the brief
+  /// comment attached to the comment providing decl.
+  StringRef getSemanticBriefComment() const;
 
   /// Returns true if there is a Clang AST node associated
   /// with self.

include/swift/AST/FileUnit.h

@@ -161,12 +161,16 @@ class FileUnit : public DeclContext, public ASTAllocated<FileUnit> {
   ///
   /// This function is an implementation detail for comment serialization.
   /// If you just want to get a comment attached to a decl, use
-  /// \c Decl::getRawComment() or \c Decl::getBriefComment().
+  /// \c Decl::getRawComment() or \c Decl::getSemanticBriefComment().
   virtual Optional<CommentInfo>
   getCommentForDecl(const Decl *D) const {
     return None;
   }
 
+  /// For a serialized AST file, returns \c true if an adjacent swiftdoc has been
+  /// loaded. Otherwise, returns \c false.
+  virtual bool hasLoadedSwiftDoc() const { return false; }
+
   virtual Optional<StringRef>
   getGroupNameForDecl(const Decl *D) const {
     return None;

include/swift/AST/TypeCheckRequests.h

@@ -4168,6 +4168,45 @@ class LocalDiscriminatorsRequest
   bool isCached() const { return true; }
 };
 
+/// Retrieve the raw documentation comment of a declaration.
+class RawCommentRequest
+    : public SimpleRequest<RawCommentRequest,
+                           RawComment(const Decl *),
+                           RequestFlags::Cached> {
+public:
+  using SimpleRequest::SimpleRequest;
+
+private:
+  friend SimpleRequest;
+
+  // Evaluation.
+  RawComment evaluate(Evaluator &evaluator, const Decl *D) const;
+
+public:
+  // Separate caching.
+  bool isCached() const { return true; }
+};
+
+/// Retrieve the brief portion of a declaration's document comment, potentially
+/// walking to find the comment providing decl if needed.
+class SemanticBriefCommentRequest
+    : public SimpleRequest<SemanticBriefCommentRequest,
+                           StringRef(const Decl *),
+                           RequestFlags::Cached> {
+public:
+  using SimpleRequest::SimpleRequest;
+
+private:
+  friend SimpleRequest;
+
+  // Evaluation.
+  StringRef evaluate(Evaluator &evaluator, const Decl *D) const;
+
+public:
+  // Separate caching.
+  bool isCached() const { return true; }
+};
+
 /// Checks that all of a class's \c \@objcImplementation extensions provide
 /// complete and correct implementations for their corresponding interfaces.
 /// This is done on all of a class's implementations at once to improve diagnostics.

include/swift/AST/TypeCheckerTypeIDZone.def

@@ -466,6 +466,12 @@ SWIFT_REQUEST(TypeChecker, GetRuntimeDiscoverableAttributes,
 SWIFT_REQUEST(TypeChecker, LocalDiscriminatorsRequest,
               unsigned(DeclContext *),
               Cached, NoLocationInfo)
+SWIFT_REQUEST(TypeChecker, RawCommentRequest,
+              RawComment(const Decl *),
+              Cached, NoLocationInfo)
+SWIFT_REQUEST(TypeChecker, SemanticBriefCommentRequest,
+              StringRef(const Decl *),
+              Cached, NoLocationInfo)
 SWIFT_REQUEST(TypeChecker, IsNonUserModuleRequest,
               bool(ModuleDecl *),
               Cached, NoLocationInfo)

include/swift/Serialization/SerializedModuleLoader.h

@@ -430,6 +430,8 @@ class SerializedASTFile final : public LoadedFile {
 
   Optional<CommentInfo> getCommentForDecl(const Decl *D) const override;
 
+  bool hasLoadedSwiftDoc() const override;
+
   Optional<StringRef> getGroupNameForDecl(const Decl *D) const override;
 
 

lib/AST/ASTContext.cpp

@@ -316,12 +316,6 @@ struct ASTContext::Implementation {
   /// actual \c SourceLocs that require opening their external buffer.
   llvm::DenseMap<const Decl *, ExternalSourceLocs *> ExternalSourceLocs;
 
-  /// Map from Swift declarations to raw comments.
-  llvm::DenseMap<const Decl *, std::pair<RawComment, bool>> RawComments;
-
-  /// Map from Swift declarations to brief comments.
-  llvm::DenseMap<const Decl *, StringRef> BriefComments;
-
   /// Map from declarations to foreign error conventions.
   /// This applies to both actual imported functions and to @objc functions.
   llvm::DenseMap<const AbstractFunctionDecl *,
@@ -2610,30 +2604,6 @@ void ASTContext::setExternalSourceLocs(const Decl *D,
   getImpl().ExternalSourceLocs[D] = Locs;
 }
 
-Optional<std::pair<RawComment, bool>> ASTContext::getRawComment(const Decl *D) {
-  auto Known = getImpl().RawComments.find(D);
-  if (Known == getImpl().RawComments.end())
-    return None;
-
-  return Known->second;
-}
-
-void ASTContext::setRawComment(const Decl *D, RawComment RC, bool FromSerialized) {
-  getImpl().RawComments[D] = std::make_pair(RC, FromSerialized);
-}
-
-Optional<StringRef> ASTContext::getBriefComment(const Decl *D) {
-  auto Known = getImpl().BriefComments.find(D);
-  if (Known == getImpl().BriefComments.end())
-    return None;
-
-  return Known->second;
-}
-
-void ASTContext::setBriefComment(const Decl *D, StringRef Comment) {
-  getImpl().BriefComments[D] = Comment;
-}
-
 NormalProtocolConformance *
 ASTContext::getConformance(Type conformingType,
                            ProtocolDecl *protocol,
@@ -2936,8 +2906,6 @@ size_t ASTContext::getTotalMemory() const {
     getImpl().Allocator.getTotalMemory() +
     getImpl().Cleanups.capacity() +
     llvm::capacity_in_bytes(getImpl().ModuleLoaders) +
-    llvm::capacity_in_bytes(getImpl().RawComments) +
-    llvm::capacity_in_bytes(getImpl().BriefComments) +
     llvm::capacity_in_bytes(getImpl().ModuleTypes) +
     llvm::capacity_in_bytes(getImpl().GenericParamTypes) +
     // getImpl().GenericFunctionTypes ?