Add docs on adding commands and config options (#1507)

* Add docs on adding commands and config options

* Update DEVELOPING.md

DEVELOPING.md

@@ -1,4 +1,16 @@
-# Environment setup
+- [Development Basics](#development-basics)
+  * [Environment setup](#environment-setup)
+  * [Testing](#testing)
+  * [Linting](#linting)
+  * [Minimum Supported Versions](#minimum-supported-versions)
+- [Adding a Command](#adding-a-command)
+- [Adding a Configuration Option](#adding-a-configuration-option)
+  * [Configuration Docstrings](#configuration-docstrings)
+  * [Triggers](#triggers)
+- [Random developer notes](#random-developer-notes)
+
+# Development Basics
+## Environment setup
 
 After installing `pwndbg` by running `setup.sh`, you additionally need to run `./setup-dev.sh` to install the necessary development dependencies.
 
@@ -12,7 +24,7 @@ If you'd like to use `docker compose`, you can run
 docker compose run -i main
 ```
 
-# Testing
+## Testing
 
 It's highly recommended you write a new test or update an existing test whenever adding new functionality to `pwndbg`.
 
@@ -46,7 +58,7 @@ def test_hexdump(start_binary):
 
 Note that in the test, we can access `pwndbg` library code like `pwndbg.gdblib.regs.rsp` as well as execute GDB commands with `gdb.execute()`.
 
-# Linting
+## Linting
 
 The `lint.sh` script runs `isort`, `black`, `flake8`, `shfmt`, and `vermin`. `isort` and `black` are able to automatically fix any issues they detect, and you can enable this by running `./lint.sh -f`. You can find the configuration files for these tools in `setup.cfg` and `pyproject.toml`.
 
@@ -59,7 +71,7 @@ You can optionally set the contents of `.git/hooks/pre-push` to the following if
 ./lint.sh || exit 1
 ```
 
-# Minimum Supported Versions
+## Minimum Supported Versions
 
 Our goal is to fully support all Ubuntu LTS releases that have not reach end-of-life, with support for other platforms on a best-effort basis. Currently that means all code should work on Ubuntu 18.04, 20.04, and 22.04 with GDB 8.1 and later. This means that the minimum supported Python version is 3.6.9, and we cannot use any newer Python features unless those features are backported to this minimum version.
 
@@ -67,17 +79,40 @@ Note that while all code should run without errors on these supported LTS versio
 
 The `lint.sh` script described in the previous section runs [`vermin`](https://github.com/netromdk/vermin) to ensure that our code does not use any features that aren't supported on Python 3.6.
 
-# Random developer notes
+# Adding a Command
 
-Feel free to update the list below!
+Create a new Python file in `pwndbg/commands/my_command.py`, replacing `my_command` with a reasonable name for the command. The most basic command looks like this:
 
-* If you want to play with pwndbg functions under GDB, you can always use GDB's `pi` which launches python interpreter or just `py <some python line>`.
+```python
+import argparse
 
-* If there is possibility, don't use `gdb.execute` as this requires us to parse the string and so on; there are some cases in which there is no other choice. Most of the time we try to wrap GDB's API to our own/easier API.
+import pwndbg.commands
+
+parser = argparse.ArgumentParser(description="Command description.")
+parser.add_argument("arg", type=str, help="An example argument.")
+
+
+@pwndbg.commands.ArgparsedCommand(parser)
+def my_command(arg: str) -> None:
+    """Print the argument"""
+    print(f"Argument is {arg}")
+```
+
+In addition, you need to import this file in the `load_commands` function in `pwndbg/commands/__init__.py`. After this, running `my_command foo` in GDB will print out "Argument is foo".
+
+# Adding a Configuration Option
+
+```python
+import pwndbg.gdblib.config
+
+pwndbg.gdblib.config.add_param("config-name", False, "example configuration option")
+```
 
-* We have our own `pwndbg.config.Parameter` (which extends `gdb.Parameter`) - all of our parameters can be seen using `config` or `theme` commands. If we want to do something when user changes config/theme - we can do it defining a function and decorating it with `pwndbg.config.Trigger`.
+`pwndbg.gdblib.config.config_name` will now refer to the value of the configuration option, and it will default to `False` if not set.
 
-* You can create a new config with `pwndbg.gdblib.config.add_param`.
+## Configuration Docstrings
+
+TODO: There are many places GDB shows docstrings, and they show up slightly differently in each place, we should give examples of this
 
 * When using `pwndbg.gdblib.config.add_param` to add a new config, there are a few things to keep in mind:
   * For the `set_show_doc` parameter, it is best to use a noun phrase like "the value of something" to ensure that the output is grammatically correct.
@@ -86,9 +121,21 @@ Feel free to update the list below!
     * See the [documentation](https://sourceware.org/gdb/onlinedocs/gdb/Parameters-In-Python.html) for more information.
     * If you use `gdb.PARAM_ENUM` as `param_class`, you must pass a list of strings to the `enum_sequence` parameter.
 
-* The dashboard/display/context we are displaying is done by `pwndbg/commands/context.py` which is invoked through GDB's prompt hook (which we defined in `pwndbg/prompt.py` as `prompt_hook_on_stop`).
+## Triggers
+
+TODO: If we want to do something when user changes config/theme - we can do it defining a function and decorating it with `pwndbg.config.Trigger`.
+
+# Random developer notes
+
+Feel free to update the list below!
 
-* All commands should be defined in `pwndbg/commands` - most of them lie in separate files but some files contains many of them (e.g. commands corresponding to windbg debugger - in `windbg.py` or some misc commands in `misc.py`). We would also want to make all of them to use `ArgparsedCommand` (instead of `Command`).
+* If you want to play with pwndbg functions under GDB, you can always use GDB's `pi` which launches python interpreter or just `py <some python line>`.
+
+* If there is possibility, don't use `gdb.execute` as this requires us to parse the string and so on; there are some cases in which there is no other choice. Most of the time we try to wrap GDB's API to our own/easier API.
+
+* We have our own `pwndbg.config.Parameter` (which extends `gdb.Parameter`) - all of our parameters can be seen using `config` or `theme` commands. 
+
+* The dashboard/display/context we are displaying is done by `pwndbg/commands/context.py` which is invoked through GDB's prompt hook (which we defined in `pwndbg/prompt.py` as `prompt_hook_on_stop`).
 
 * We change a bit GDB settings - this can be seen in `pwndbg/__init__.py` - there are also imports for all pwndbg submodules
 
@@ -106,6 +153,4 @@ Feel free to update the list below!
 
 * Some of pwndbg's functionality - e.g. memory fetching - require us to have an instance of proper `gdb.Type` - the problem with that is that there is no way to define our own types - we have to ask gdb if it detected particular type in this particular binary (that sucks). We do it in `pwndbg/typeinfo.py` and it works most of the time. The known bug with that is that it might not work properly for Golang binaries compiled with debugging symbols.
 
-* We would like to add proper tests for pwndbg - see tests framework PR if you want to help on that.
-
 * If you want to use `gdb.parse_and_eval("a_function_name()")` or something similar that call a function, please remember this might cause another thread to continue execution without `set scheduler-locking on`. If you didn't expect that, you should use `parse_and_eval_with_scheduler_lock` from `pwndbg.gdblib.scheduler` instead.