Author: Raphael Isemann Date: 2020-01-03T10:38:38+01:00 New Revision: 1711f886fd801581b6b5505cc165c977294d311a
URL: https://github.com/llvm/llvm-project/commit/1711f886fd801581b6b5505cc165c977294d311a DIFF: https://github.com/llvm/llvm-project/commit/1711f886fd801581b6b5505cc165c977294d311a.diff LOG: [lldb][NFC] Document TypeSystem and related Compiler* classes Added: Modified: lldb/include/lldb/Symbol/CompilerDecl.h lldb/include/lldb/Symbol/CompilerDeclContext.h lldb/include/lldb/Symbol/CompilerType.h lldb/include/lldb/Symbol/TypeSystem.h Removed: ################################################################################ diff --git a/lldb/include/lldb/Symbol/CompilerDecl.h b/lldb/include/lldb/Symbol/CompilerDecl.h index e4687ffb3853..4fd269d4730e 100644 --- a/lldb/include/lldb/Symbol/CompilerDecl.h +++ b/lldb/include/lldb/Symbol/CompilerDecl.h @@ -15,11 +15,25 @@ namespace lldb_private { +/// Represents a generic declaration such as a function declaration. +/// +/// This class serves as an abstraction for a declaration inside one of the +/// TypeSystems implemented by the language plugins. It does not have any actual +/// logic in it but only stores an opaque pointer and a pointer to the +/// TypeSystem that gives meaning to this opaque pointer. All methods of this +/// class should call their respective method in the TypeSystem interface and +/// pass the opaque pointer along. +/// +/// \see lldb_private::TypeSystem class CompilerDecl { public: // Constructors and Destructors CompilerDecl() = default; + /// Creates a CompilerDecl with the given TypeSystem and opaque pointer. + /// + /// This constructor should only be called from the respective TypeSystem + /// implementation. CompilerDecl(TypeSystem *type_system, void *decl) : m_type_system(type_system), m_opaque_decl(decl) {} diff --git a/lldb/include/lldb/Symbol/CompilerDeclContext.h b/lldb/include/lldb/Symbol/CompilerDeclContext.h index 719515242890..6db6f4d3f623 100644 --- a/lldb/include/lldb/Symbol/CompilerDeclContext.h +++ b/lldb/include/lldb/Symbol/CompilerDeclContext.h @@ -16,6 +16,17 @@ namespace lldb_private { +/// Represents a generic declaration context in a program. A declaration context +/// is data structure that contains declarations (e.g. namespaces). +/// +/// This class serves as an abstraction for a declaration context inside one of +/// the TypeSystems implemented by the language plugins. It does not have any +/// actual logic in it but only stores an opaque pointer and a pointer to the +/// TypeSystem that gives meaning to this opaque pointer. All methods of this +/// class should call their respective method in the TypeSystem interface and +/// pass the opaque pointer along. +/// +/// \see lldb_private::TypeSystem class CompilerDeclContext { public: /// Constructs an invalid CompilerDeclContext. @@ -24,9 +35,10 @@ class CompilerDeclContext { /// Constructs a CompilerDeclContext with the given opaque decl context /// and its respective TypeSystem instance. /// - /// Do not use this constructor directly but instead call the respective - /// wrapper from the TypeSystem subclass. - /// @see lldb_private::ClangASTContext::CreateDeclContext(clang::DeclContext*) + /// This constructor should only be called from the respective TypeSystem + /// implementation. + /// + /// \see lldb_private::ClangASTContext::CreateDeclContext(clang::DeclContext*) CompilerDeclContext(TypeSystem *type_system, void *decl_ctx) : m_type_system(type_system), m_opaque_decl_ctx(decl_ctx) {} diff --git a/lldb/include/lldb/Symbol/CompilerType.h b/lldb/include/lldb/Symbol/CompilerType.h index 660466be6b30..37e826291c88 100644 --- a/lldb/include/lldb/Symbol/CompilerType.h +++ b/lldb/include/lldb/Symbol/CompilerType.h @@ -20,16 +20,24 @@ namespace lldb_private { class DataExtractor; -// A class that can carry around a clang ASTContext and a opaque clang -// QualType. A clang::QualType can be easily reconstructed from an opaque clang -// type and often the ASTContext is needed when doing various type related -// tasks, so this class allows both items to travel in a single very -// lightweight class that can be used. There are many static equivalents of the -// member functions that allow the ASTContext and the opaque clang QualType to -// be specified for ease of use and to avoid code duplication. +/// Represents a generic type in a programming language. +/// +/// This class serves as an abstraction for a type inside one of the TypeSystems +/// implemented by the language plugins. It does not have any actual logic in it +/// but only stores an opaque pointer and a pointer to the TypeSystem that +/// gives meaning to this opaque pointer. All methods of this class should call +/// their respective method in the TypeSystem interface and pass the opaque +/// pointer along. +/// +/// \see lldb_private::TypeSystem class CompilerType { public: - // Constructors and Destructors + /// Creates a CompilerType with the given TypeSystem and opaque compiler type. + /// + /// This constructor should only be called from the respective TypeSystem + /// implementation. + /// + /// \see lldb_private::ClangASTContext::GetType(clang::QualType) CompilerType(TypeSystem *type_system, lldb::opaque_compiler_type_t type) : m_type(type), m_type_system(type_system) {} diff --git a/lldb/include/lldb/Symbol/TypeSystem.h b/lldb/include/lldb/Symbol/TypeSystem.h index 706831f7ee98..91f751acf6c7 100644 --- a/lldb/include/lldb/Symbol/TypeSystem.h +++ b/lldb/include/lldb/Symbol/TypeSystem.h @@ -49,7 +49,25 @@ struct LanguageSet { bool operator[](unsigned i) const; }; -/// Interface for representing the Type Systems in diff erent languages. +/// Interface for representing a type system. +/// +/// Implemented by language plugins to define the type system for a given +/// language. +/// +/// This interface extensively used opaque pointers to prevent that generic +/// LLDB code has dependencies on language plugins. The type and semantics of +/// these opaque pointers are defined by the TypeSystem implementation inside +/// the respective language plugin. Opaque pointers from one TypeSystem +/// instance should never be passed to a diff erent TypeSystem instance (even +/// when the language plugin for both TypeSystem instances is the same). +/// +/// Most of the functions in this class should not be called directly but only +/// called by their respective counterparts in CompilerType, CompilerDecl and +/// CompilerDeclContext. +/// +/// \see lldb_private::CompilerType +/// \see lldb_private::CompilerDecl +/// \see lldb_private::CompilerDeclContext class TypeSystem : public PluginInterface { public: // Constructors and Destructors _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
