add some numpy-style documentation to core objects

Author: tony

libtmux/pane.py

@@ -16,13 +16,32 @@
 
 
 class Pane(TmuxMappingObject, TmuxRelationalObject):
+    """
+    A :term:`tmux(1)` :term:`pane` [#]_.
+
+    ``Pane`` instances can send commands directly to a pane, or traverse
+    between linked tmux objects.
 
-    """:term:`tmux(1)` :term:`pane`.
+    Parameters
+    ----------
+    window : :class:`Window`
 
-    :param window: :class:`Window`
+    Notes
+    -----
 
     .. versionchanged:: 0.8
         Renamed from ``.tmux`` to ``.cmd``.
+
+    References
+    ----------
+
+    .. [#] tmux pane. openbsd manpage for TMUX(1).
+           "Each window displayed by tmux may be split into one or more
+           panes; each pane takes up a certain area of the display and is
+           a separate terminal."
+
+       https://man.openbsd.org/tmux.1#WINDOWS_AND_PANES.
+       Accessed April 1st, 2018.
     """
     #: namespace used :class:`~libtmux.common.TmuxMappingObject`
     formatter_prefix = 'pane_'

libtmux/server.py

@@ -20,7 +20,8 @@
 
 class Server(TmuxRelationalObject, EnvironmentMixin):
 
-    """The :term:`tmux(1)` server.
+    """
+    The :term:`tmux(1)` :term:`server` [#]_.
 
     - :attr:`Server._sessions` [:class:`Session`, ...]
 
@@ -32,6 +33,25 @@ class Server(TmuxRelationalObject, EnvironmentMixin):
 
     When instantiated stores information on live, running tmux server.
 
+    Parameters
+    ----------
+    socket_name : str, optional
+    socket_path : str, optional
+    config_file : str, optional
+    colors : str, optional
+
+    References
+    ----------
+    .. [#] CLIENTS AND SESSIONS. openbsd manpage for TMUX(1)
+           "The tmux server manages clients, sessions, windows and panes.
+           Clients are attached to sessions to interact with them, either when
+           they are created with the new-session command, or later with the
+           attach-session command. Each session has one or more windows linked
+           into it. Windows may be linked to multiple sessions and are made up
+           of one or more panes, each of which contains a pseudo terminal."
+
+       https://man.openbsd.org/tmux.1#CLIENTS_AND_SESSIONS.
+       Accessed April 1st, 2018.
     """
 
     #: ``[-L socket-name]``

libtmux/session.py

@@ -24,9 +24,26 @@ class Session(
     TmuxRelationalObject,
     EnvironmentMixin
 ):
-    """:term:`tmux(1)` session.
+    """
+    A :term:`tmux(1)` :term:`session` [#]_.
 
     Holds :class:`Window` objects.
+
+    Parameters
+    ----------
+    server : :class:`Server`
+
+    References
+    ----------
+    .. [#] tmux session. openbsd manpage for TMUX(1).
+           "When tmux is started it creates a new session with a single window
+           and displays it on screen..."
+
+           "A session is a single collection of pseudo terminals under the
+           management of tmux.  Each session has one or more windows linked to
+           it."
+
+       https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed April 1st, 2018.
     """
 
     #: unique child ID key for :class:`~libtmux.common.TmuxRelationalObject`

libtmux/window.py

@@ -21,7 +21,24 @@
 
 
 class Window(TmuxMappingObject, TmuxRelationalObject):
-    """:term:`tmux(1)` window."""
+    """
+    A :term:`tmux(1)` :term:`window` [#]_.
+
+    Holds :class:`Pane` objects.
+
+    Parameters
+    ----------
+    session : :class:`Session`
+
+    References
+    ----------
+    .. [#] tmux window. openbsd manpage for TMUX(1).
+           "Each session has one or more windows linked to it. A window
+           occupies the entire screen and may be split into rectangular
+           panes..."
+
+       https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed April 1st, 2018.
+    """
 
     #: unique child ID key for :class:`~libtmux.common.TmuxRelationalObject`
     child_id_attribute = 'pane_id'