Show various options for documenting attributes

3 files changed, 59 insertions, 19 deletions

diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py
index 1eeb4212..9f2dd329 100644
--- a/cmd2/cmd2.py
+++ b/cmd2/cmd2.py
@@ -292,8 +292,8 @@ class Cmd(cmd.Cmd):
 
         # The error that prints when a non-existent command is run
         self.default_error = "{} is not a recognized command, alias, or macro"
+        """The error message displayed when a non-existent command is run."""
 
-        # If this string is non-empty, then this warning message will print if a broken pipe error occurs while printing
         self.broken_pipe_warning = ''
 
         # Commands that will run at the beginning of the command loop
@@ -416,6 +416,20 @@ class Cmd(cmd.Cmd):
             self.perror('Invalid value: {} (valid values: {}, {}, {})'.format(new_val, ansi.ANSI_TERMINAL,
                                                                               ansi.ANSI_ALWAYS, ansi.ANSI_NEVER))
 
+    @property
+    def broken_pipe_warning(self) -> str:
+        """Message to display if a BrokenPipeError is raised while writing output.
+
+        :meth:`~cmd2.cmd2.Cmd.poutput()` catches BrokenPipeError exceptions and
+        outputs the contents of `broken_pipe_warning`. The default value is an
+        empty string meaning the BrokenPipeError is silently swallowed.
+        """
+        return self.broken_pipe_error
+
+    @broken_pipe_warning.setter
+    def broken_pipe_warning(self, new_val: str) -> None:
+        self.broken_pipe_error = new_val
+
     def _completion_supported(self) -> bool:
         """Return whether tab completion is supported"""
         return self.use_rawinput and self.completekey and rl_type != RlType.NONE
diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst
index 4f88101e..ebec17c3 100644
--- a/docs/api/cmd.rst
+++ b/docs/api/cmd.rst
@@ -3,3 +3,7 @@ cmd2.Cmd
 
 .. autoclass:: cmd2.cmd2.Cmd
     :members:
+
+    .. attribute:: default_error
+
+
diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst
index 16ff044d..58e53962 100644
--- a/docs/features/generating_output.rst
+++ b/docs/features/generating_output.rst
@@ -38,18 +38,25 @@ TODO:
 Ordinary Output
 ---------------
 
-The ``poutput()`` method is almost like using the Python built-in ``print()``
-function. ``poutput()`` adds two conveniences.
+The :meth:`.cmd2.Cmd.poutput` method is similar to the Python
+`built-in print function <https://docs.python.org/3/library/functions.html#print>`_. :meth:`~cmd2.cmd2.Cmd.poutput` adds two
+conveniences.
 
-Since users can pipe output to a shell command, it catches ``BrokenPipeError``
-and outputs the contents of ``self.broken_pipe_warning`` to ``stderr``.
-``self.broken_pipe_warning`` defaults to an empty string so this method will
-just swallow the exception. If you want to show some error message, put it in
-``self.broken_pipe_warning`` when you initialize ``Cmd2.cmd``.
+  1. Since users can pipe output to a shell command, it catches
+  ``BrokenPipeError`` and outputs the contents of
+  ``self.broken_pipe_warning`` to ``stderr``. ``self.broken_pipe_warning``
+  defaults to an empty string so this method will just swallow the exception.
+  If you want to show an error message, put it in
+  ``self.broken_pipe_warning`` when you initialize ``Cmd2.cmd``.
 
-``poutput()`` also honors the :ref:`features/settings:allow_ansi` setting,
-which controls whether ANSI escape sequences that instruct the terminal to
-colorize output are stripped from the output.
+  2. It examines and honors the :ref:`features/settings:allow_ansi` setting.
+  See :ref:`features/generating_output:Colored Output` below for more details.
+
+Here's a simple command that shows this method in action::
+
+    def do_echo(self, args):
+        """A simple command showing how poutput() works"""
+        self.poutput(args)
 
 
 Colored Output
@@ -68,17 +75,35 @@ running on Windows, it wraps ``stdout``, looks for ANSI escape sequences, and
 converts them into the appropriate ``win32`` calls to modify the state of the
 terminal.
 
-``cmd2`` imports and uses Colorama and also provides a number of convenience
-methods for generating colorized output, measuring the screen width of
-colorized output, setting the window title in the terminal, and removing ANSI
-escape codes from a string. These functions are all documentated in
-:ref:`api/ansi:cmd2.ansi`.
+``cmd2`` imports and uses Colorama and provides a number of convenience methods
+for generating colorized output, measuring the screen width of colorized
+output, setting the window title in the terminal, and removing ANSI escape
+codes from a string. These functions are all documentated in
+:mod:`cmd2.ansi`.
+
+:mod:`cmd2.cmd2.Cmd` includes an :ref:`features/settings:allow_ansi` setting,
+which controls whether ANSI escape sequences that instruct the terminal to
+colorize output are stripped from the output. The recommended approach is to
+construct your application so that it generates colorized output, and then
+allow your users to use this setting to remove the colorization if they do not
+want it.
+
+Output generated by any of these
+methods will honor the :ref:`features/settings:allow_ansi` setting:
+
+- :meth:`cmd2.cmd2.Cmd.poutput`
+- :meth:`cmd2.cmd2.Cmd.perror`
+- :meth:`cmd2.cmd2.Cmd.pwarning`
+- :meth:`cmd2.cmd2.Cmd.pexcept`
+- :meth:`cmd2.cmd2.Cmd.pfeedback`
+- :meth:`cmd2.cmd2.Cmd.ppaged`
 
 
 Error Messages
 --------------
 
 
+
 Warning Messages
 ----------------
 
@@ -121,6 +146,3 @@ Columnar Output
 ---------------
 
 Using wcswidth() and ansi.ansi_safe_wcswidth()
-
-
-