llvm/clang/include/clang/ExtractAPI/API.h

//===- ExtractAPI/API.h -----------------------------------------*- 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
//
//===----------------------------------------------------------------------===//
///
/// \file
/// This file defines the APIRecord-based structs and the APISet class.
///
/// Clang ExtractAPI is a tool to collect API information from a given set of
/// header files. The structures in this file describe data representations of
/// the API information collected for various kinds of symbols.
///
//===----------------------------------------------------------------------===//

#ifndef LLVM_CLANG_EXTRACTAPI_API_H
#define LLVM_CLANG_EXTRACTAPI_API_H

#include "clang/AST/Availability.h"
#include "clang/AST/DeclBase.h"
#include "clang/AST/RawCommentList.h"
#include "clang/Basic/SourceLocation.h"
#include "clang/ExtractAPI/DeclarationFragments.h"
#include "llvm/ADT/SmallVector.h"
#include "llvm/Support/Allocator.h"
#include "llvm/Support/Casting.h"
#include "llvm/TargetParser/Triple.h"
#include <cstddef>
#include <iterator>
#include <memory>
#include <optional>
#include <type_traits>

namespace clang {
namespace extractapi {

class Template { … };

/// DocComment is a vector of RawComment::CommentLine.
///
/// Each line represents one line of striped documentation comment,
/// with source range information. This simplifies calculating the source
/// location of a character in the doc comment for pointing back to the source
/// file.
/// e.g.
/// \code
///   /// This is a documentation comment
///       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~'  First line.
///   ///     with multiple lines.
///       ^~~~~~~~~~~~~~~~~~~~~~~'         Second line.
/// \endcode
DocComment;

struct APIRecord;

// This represents a reference to another symbol that might come from external
/// sources.
struct SymbolReference { … };

class RecordContext;

// Concrete classes deriving from APIRecord need to have a construct with first
// arguments USR, and Name, in that order. This is so that they
// are compatible with `APISet::createRecord`.
// When adding a new kind of record don't forget to update APIRecords.inc!
/// The base representation of an API record. Holds common symbol information.
struct APIRecord { … };

/// Base class used for specific record types that have children records this is
/// analogous to the DeclContext for the AST
class RecordContext { … };

struct NamespaceRecord : APIRecord, RecordContext { … };

/// This holds information associated with global functions.
struct GlobalFunctionRecord : APIRecord { … };

struct GlobalFunctionTemplateRecord : GlobalFunctionRecord { … };

struct GlobalFunctionTemplateSpecializationRecord : GlobalFunctionRecord { … };

/// This holds information associated with global functions.
struct GlobalVariableRecord : APIRecord, RecordContext { … };

struct GlobalVariableTemplateRecord : GlobalVariableRecord { … };

struct GlobalVariableTemplateSpecializationRecord : GlobalVariableRecord { … };

struct GlobalVariableTemplatePartialSpecializationRecord
    : GlobalVariableRecord { … };

/// This holds information associated with enum constants.
struct EnumConstantRecord : APIRecord { … };

struct TagRecord : APIRecord, RecordContext { … };

/// This holds information associated with enums.
struct EnumRecord : TagRecord { … };

/// This holds information associated with struct or union fields fields.
struct RecordFieldRecord : APIRecord, RecordContext { … };

/// This holds information associated with structs and unions.
struct RecordRecord : TagRecord { … };

struct StructFieldRecord : RecordFieldRecord { … };

struct StructRecord : RecordRecord { … };

struct UnionFieldRecord : RecordFieldRecord { … };

struct UnionRecord : RecordRecord { … };

struct CXXFieldRecord : APIRecord, RecordContext { … };

struct CXXFieldTemplateRecord : CXXFieldRecord { … };

struct CXXMethodRecord : APIRecord { … };

struct CXXConstructorRecord : CXXMethodRecord { … };

struct CXXDestructorRecord : CXXMethodRecord { … };

struct CXXStaticMethodRecord : CXXMethodRecord { … };

struct CXXInstanceMethodRecord : CXXMethodRecord { … };

struct CXXMethodTemplateRecord : CXXMethodRecord { … };

struct CXXMethodTemplateSpecializationRecord : CXXMethodRecord { … };

/// This holds information associated with Objective-C properties.
struct ObjCPropertyRecord : APIRecord { … };

struct ObjCInstancePropertyRecord : ObjCPropertyRecord { … };

struct ObjCClassPropertyRecord : ObjCPropertyRecord { … };

/// This holds information associated with Objective-C instance variables.
struct ObjCInstanceVariableRecord : APIRecord { … };

/// This holds information associated with Objective-C methods.
struct ObjCMethodRecord : APIRecord { … };

struct ObjCInstanceMethodRecord : ObjCMethodRecord { … };

struct ObjCClassMethodRecord : ObjCMethodRecord { … };

struct StaticFieldRecord : CXXFieldRecord { … };

/// The base representation of an Objective-C container record. Holds common
/// information associated with Objective-C containers.
struct ObjCContainerRecord : APIRecord, RecordContext { … };

struct CXXClassRecord : RecordRecord { … };

struct ClassTemplateRecord : CXXClassRecord { … };

struct ClassTemplateSpecializationRecord : CXXClassRecord { … };

struct ClassTemplatePartialSpecializationRecord : CXXClassRecord { … };

struct ConceptRecord : APIRecord { … };

/// This holds information associated with Objective-C categories.
struct ObjCCategoryRecord : ObjCContainerRecord { … };

/// This holds information associated with Objective-C interfaces/classes.
struct ObjCInterfaceRecord : ObjCContainerRecord { … };

/// This holds information associated with Objective-C protocols.
struct ObjCProtocolRecord : ObjCContainerRecord { … };

/// This holds information associated with macro definitions.
struct MacroDefinitionRecord : APIRecord { … };

/// This holds information associated with typedefs.
///
/// Note: Typedefs for anonymous enums and structs typically don't get emitted
/// by the serializers but still get a TypedefRecord. Instead we use the
/// typedef name as a name for the underlying anonymous struct or enum.
struct TypedefRecord : APIRecord { … };

/// APISet holds the set of API records collected from given inputs.
class APISet { … };

template <typename RecordTy, typename... CtorArgsContTy>
typename std::enable_if_t<std::is_base_of_v<APIRecord, RecordTy>, RecordTy> *
APISet::createRecord(StringRef USR, StringRef Name,
                     CtorArgsContTy &&...CtorArgs) { … }

// Helper type for implementing casting to RecordContext pointers.
// Selected when FromTy not a known subclass of RecordContext.
template <typename FromTy,
          bool IsKnownSubType = std::is_base_of_v<RecordContext, FromTy>>
struct ToRecordContextCastInfoWrapper {
  static_assert(std::is_base_of_v<APIRecord, FromTy>,
                "Can only cast APIRecord and derived classes to RecordContext");

  static bool isPossible(FromTy *From) { … }

  static RecordContext *doCast(FromTy *From) { … }
};

// Selected when FromTy is a known subclass of RecordContext.
ToRecordContextCastInfoWrapper<FromTy, true>;

// Helper type for implementing casting to RecordContext pointers.
// Selected when ToTy isn't a known subclass of RecordContext
template <typename ToTy,
          bool IsKnownSubType = std::is_base_of_v<RecordContext, ToTy>>
struct FromRecordContextCastInfoWrapper {
  static_assert(
      std::is_base_of_v<APIRecord, ToTy>,
      "Can only class RecordContext to APIRecord and derived classes");

  static bool isPossible(RecordContext *Ctx) { … }

  static ToTy *doCast(RecordContext *Ctx) { … }
};

// Selected when ToTy is a known subclass of RecordContext.
FromRecordContextCastInfoWrapper<ToTy, true>;

} // namespace extractapi
} // namespace clang

// Implement APIRecord (and derived classes) to and from RecordContext
// conversions
namespace llvm {

CastInfo< ::clang::extractapi::RecordContext, FromTy *>;

CastInfo< ::clang::extractapi::RecordContext, const FromTy *>;

CastInfo<ToTy, ::clang::extractapi::RecordContext *>;

CastInfo<ToTy, const ::clang::extractapi::RecordContext *>;

} // namespace llvm

#endif // LLVM_CLANG_EXTRACTAPI_API_H