[Lldb-commits] [lldb] 1711f88 - [lldb][NFC] Document TypeSystem and related Compiler* classes

[Raphael Isemann via lldb-commits]

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