Add more documentation

drgn/__init__.py

@@ -1 +1,37 @@
+# Copyright 2018 - Omar Sandoval
+# SPDX-License-Identifier: GPL-3.0+
+
+"""
+Scriptable debugger library
+
+drgn is a scriptable debugger. It is built on top of Python, so if you don't
+know at least a little bit of Python, go learn it first.
+
+drgn supports an interactive mode and a script mode. Both are simply a Python
+interpreter initialized with a special drgn.program.Program object named "prog"
+that represents the program which is being debugged.
+
+In interactive mode, try
+
+>>> help(prog)
+
+or
+
+>>> import drgn.program
+>>> help(drgn.program.Program)
+
+to learn more about how to use it.
+
+Variables are represented by drgn.program.ProgramObject objects. Try
+
+>>> import drgn.program
+>>> help(drgn.program.ProgramObject)
+
+
+Types are represented by drgn.type.Type objects. Try
+
+>>> import drgn.type
+>>> help(drgn.type)
+"""
+
 __version__ = '0.1.0'

drgn/cli.py

@@ -11,7 +11,7 @@ import runpy
 import sys
 from typing import Any, Dict, List, Tuple, Union
 
-from drgn import __version__
+import drgn
 from drgn.dwarf import DW_TAG
 from drgn.dwarfindex import DwarfIndex
 from drgn.elf import parse_elf_phdrs
@@ -50,7 +50,7 @@ def find_modules(release: str) -> List[str]:
 
 def main() -> None:
     python_version = '.'.join(str(v) for v in sys.version_info[:3])
-    version = f'drgn {__version__} (using Python {python_version})'
+    version = f'drgn {drgn.__version__} (using Python {python_version})'
     parser = argparse.ArgumentParser(
         prog='drgn', description='Scriptable debugger')
     parser.add_argument(
@@ -113,6 +113,7 @@ def main() -> None:
             'prog': Program(lookup_type_fn=lookup_type,
                             lookup_variable_fn=lookup_variable,
                             read_memory_fn=read_memory),
+            'drgn': drgn,
         }
         if args.script:
             sys.argv = args.script
@@ -121,8 +122,9 @@ def main() -> None:
         else:
             init_globals['__name__'] = '__main__'
             init_globals['__doc__'] = None
-            code.interact(banner=version, exitmsg='', local=init_globals)  # type: ignore
-                                                                           # typeshed issue #2024
+            banner = version + '\nFor help, type help(drgn).'
+            code.interact(banner=banner, exitmsg='', local=init_globals)  # type: ignore
+                                                                          # typeshed issue #2024
 
 if __name__ == '__main__':
     main()

drgn/program.py

@@ -1,6 +1,8 @@
 # Copyright 2018 - Omar Sandoval
 # SPDX-License-Identifier: GPL-3.0+
 
+"""Program debugging library"""
+
 from drgn.type import (
     ArrayType,
     CompoundType,
@@ -23,11 +25,13 @@ class ProgramObject:
 
     repr() (the default at the interactive prompt) of a ProgramObject returns a
     Python representation of the object.
+
     >>> prog['jiffies']
     ProgramObject(address=0xffffffffbf005000, type=<volatile long unsigned int>)
 
     str() (which is used by print()) returns a representation of the object in
     C syntax.
+
     >>> print(prog['jiffies'])
     (volatile long unsigned int)4326237045
 

drgn/type.py

@@ -1,6 +1,17 @@
 # Copyright 2018 - Omar Sandoval
 # SPDX-License-Identifier: GPL-3.0+
 
+"""
+Source program type representation
+
+Types in a program are represented by objects of the Type class and its
+subclasses. Different subclasses have different members describing the type,
+like its name, qualifiers, signedness, etc. All subclasses of Type support
+pretty-printing with str(type_obj) and getting the size in bytes with
+type_obj.sizeof(). See the class documentation for more details, especially
+help(Type).
+"""
+
 from collections import OrderedDict
 from drgn.dwarfindex import DwarfIndex
 from drgn.dwarf import (
@@ -43,6 +54,7 @@ class Type:
 
     str() (which is used by print()) returns a representation of the type in C
     syntax.
+
     >>> print(prog['init_task'].fs.root.type_)
     struct path {
             struct vfsmount *mnt;
@@ -50,6 +62,7 @@ class Type:
     }
 
     A Type can have qualifiers as is the case in C.
+
     >>> prog['jiffies'].type_.qualifiers
     frozenset({'volatile'})
 
@@ -78,19 +91,32 @@ class Type:
         raise NotImplementedError()
 
     def read(self, buffer: bytes, offset: int = 0) -> Any:
-        """Return the buffer at the given offset interpreted as this type."""
+        """
+        Return the buffer at the given offset interpreted as this type.
+
+        This is used internally by drgn and typically doesn't need to be used
+        directly.
+        """
         raise NotImplementedError()
 
     def pretty(self, value: Any, cast: bool = True) -> str:
         """
         Return a representation of the value returned from self.read() in C
         syntax, optionally with an explicit cast to the name of this type.
+
+        This is used internally by drgn and typically doesn't need to be used
+        directly.
         """
         raise NotImplementedError()
 
     def read_pretty(self, buffer: bytes, offset: int = 0, *,
                     cast: bool = True) -> str:
-        """Return self.pretty(self.read(...))."""
+        """
+        Return self.pretty(self.read(...)).
+
+        This is used internally by drgn and typically doesn't need to be used
+        directly.
+        """
         return self.pretty(self.read(buffer, offset), cast)