//===--- RawCommentList.h - Classes for processing raw comments -*- C++ -*-===//

//

// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.

// See https://llvm.org/LICENSE.txt for license information.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

//

//===----------------------------------------------------------------------===//

#ifndef LLVM_CLANG_AST_RAWCOMMENTLIST_H

#define LLVM_CLANG_AST_RAWCOMMENTLIST_H

#include "clang/Basic/CommentOptions.h"

#include "clang/Basic/SourceLocation.h"

#include "llvm/ADT/ArrayRef.h"

#include "llvm/ADT/DenseMap.h"

#include "llvm/Support/Allocator.h"

#include <map>

namespace clang {

class ASTContext;

class ASTReader;

class Decl;

class DiagnosticsEngine;

class Preprocessor;

class SourceManager;

namespace comments {

  class FullComment;

} // end namespace comments

class RawComment {

public:

  enum CommentKind {

    RCK_Invalid,      ///< Invalid comment

    RCK_OrdinaryBCPL, ///< Any normal BCPL comments

    RCK_OrdinaryC,    ///< Any normal C comment

    RCK_BCPLSlash,    ///< \code /// stuff \endcode

    RCK_BCPLExcl,     ///< \code //! stuff \endcode

    RCK_JavaDoc,      ///< \code /** stuff */ \endcode

    RCK_Qt,           ///< \code /*! stuff */ \endcode, also used by HeaderDoc

    RCK_Merged        ///< Two or more documentation comments merged together

  };

  RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { }

  RawComment(const SourceManager &SourceMgr, SourceRange SR,

             const CommentOptions &CommentOpts, bool Merged);

  CommentKind getKind() const LLVM_READONLY {

    return (CommentKind) Kind;

  }

  bool isInvalid() const LLVM_READONLY {

    return Kind == RCK_Invalid;

  }

  bool isMerged() const LLVM_READONLY {

    return Kind == RCK_Merged;

  }

  /// Is this comment attached to any declaration?

  bool isAttached() const LLVM_READONLY {

    return IsAttached;

  }

  void setAttached() {

    IsAttached = true;

  }

  /// Returns true if it is a comment that should be put after a member:

  /// \code ///< stuff \endcode

  /// \code //!< stuff \endcode

  /// \code /**< stuff */ \endcode

  /// \code /*!< stuff */ \endcode

  bool isTrailingComment() const LLVM_READONLY {

    return IsTrailingComment;

  }

  /// Returns true if it is a probable typo:

  /// \code //< stuff \endcode

  /// \code /*< stuff */ \endcode

  bool isAlmostTrailingComment() const LLVM_READONLY {

    return IsAlmostTrailingComment;

  }

  /// Returns true if this comment is not a documentation comment.

  bool isOrdinary() const LLVM_READONLY {

    return ((Kind == RCK_OrdinaryBCPL) || 
(Kind == RCK_OrdinaryC)21.6M
);

  }

  /// Returns true if this comment any kind of a documentation comment.

  bool isDocumentation() const LLVM_READONLY {

    return !isInvalid() && !isOrdinary();

  }

  /// Returns raw comment text with comment markers.

  StringRef getRawText(const SourceManager &SourceMgr) const {

    if (RawTextValid)

      return RawText;

    RawText = getRawTextSlow(SourceMgr);

    RawTextValid = true;

    return RawText;

  }

  SourceRange getSourceRange() const LLVM_READONLY { return Range; }

  SourceLocation getBeginLoc() const LLVM_READONLY { return Range.getBegin(); }

  SourceLocation getEndLoc() const LLVM_READONLY { return Range.getEnd(); }

  const char *getBriefText(const ASTContext &Context) const {

    if (BriefTextValid)

      return BriefText;

    return extractBriefText(Context);

  }

  /// Returns sanitized comment text, suitable for presentation in editor UIs.

  /// E.g. will transform:

  ///     // This is a long multiline comment.

  ///     //   Parts of it  might be indented.

  ///     /* The comments styles might be mixed. */

  ///  into

  ///     "This is a long multiline comment.\n"

  ///     "  Parts of it  might be indented.\n"

  ///     "The comments styles might be mixed."

  /// Also removes leading indentation and sanitizes some common cases:

  ///     /* This is a first line.

  ///      *   This is a second line. It is indented.

  ///      * This is a third line. */

  /// and

  ///     /* This is a first line.

  ///          This is a second line. It is indented.

  ///     This is a third line. */

  /// will both turn into:

  ///     "This is a first line.\n"

  ///     "  This is a second line. It is indented.\n"

  ///     "This is a third line."

  std::string getFormattedText(const SourceManager &SourceMgr,

                               DiagnosticsEngine &Diags) const;

  struct CommentLine {

    std::string Text;

    PresumedLoc Begin;

    PresumedLoc End;

    CommentLine(StringRef Text, PresumedLoc Begin, PresumedLoc End)

        : Text(Text), Begin(Begin), End(End) {}

  };

  /// Returns sanitized comment text as separated lines with locations in

  /// source, suitable for further processing and rendering requiring source

  /// locations.

  std::vector<CommentLine> getFormattedLines(const SourceManager &SourceMgr,

                                             DiagnosticsEngine &Diags) const;

  /// Parse the comment, assuming it is attached to decl \c D.

  comments::FullComment *parse(const ASTContext &Context,

                               const Preprocessor *PP, const Decl *D) const;

private:

  SourceRange Range;

  mutable StringRef RawText;

  mutable const char *BriefText;

  mutable bool RawTextValid : 1;   ///< True if RawText is valid

  mutable bool BriefTextValid : 1; ///< True if BriefText is valid

  unsigned Kind : 3;

  /// True if comment is attached to a declaration in ASTContext.

  bool IsAttached : 1;

  bool IsTrailingComment : 1;

  bool IsAlmostTrailingComment : 1;

  /// Constructor for AST deserialization.

  RawComment(SourceRange SR, CommentKind K, bool IsTrailingComment,

             bool IsAlmostTrailingComment) :

    Range(SR), RawTextValid(false), BriefTextValid(false), Kind(K),

    IsAttached(false), IsTrailingComment(IsTrailingComment),

    IsAlmostTrailingComment(IsAlmostTrailingComment)

  { }

  StringRef getRawTextSlow(const SourceManager &SourceMgr) const;

  const char *extractBriefText(const ASTContext &Context) const;

  friend class ASTReader;

};

/// This class represents all comments included in the translation unit,

/// sorted in order of appearance in the translation unit.

class RawCommentList {

public:

  RawCommentList(SourceManager &SourceMgr) : SourceMgr(SourceMgr) {}

  void addComment(const RawComment &RC, const CommentOptions &CommentOpts,

                  llvm::BumpPtrAllocator &Allocator);

  /// \returns A mapping from an offset of the start of the comment to the

  /// comment itself, or nullptr in case there are no comments in \p File.

  const std::map<unsigned, RawComment *> *getCommentsInFile(FileID File) const;

  bool empty() const;

  unsigned getCommentBeginLine(RawComment *C, FileID File,

                               unsigned Offset) const;

  unsigned getCommentEndOffset(RawComment *C) const;

private:

  SourceManager &SourceMgr;

  // mapping: FileId -> comment begin offset -> comment

  llvm::DenseMap<FileID, std::map<unsigned, RawComment *>> OrderedComments;

  mutable llvm::DenseMap<RawComment *, unsigned> CommentBeginLine;

  mutable llvm::DenseMap<RawComment *, unsigned> CommentEndOffset;

  friend class ASTReader;

  friend class ASTWriter;

};

} // end namespace clang

#endif