Repository: pymeasure/pymeasure

Issue:
Improve documentation
Migrated from TODO


Discussion:
PRs welcome!
Doctests in both pymeasure code and runnable examples in the documentation would be useful, see [here](https://github.com/ralph-group/pymeasure/issues/98#issuecomment-317273099).
I found this a good, short, read about what constitutes good documentation: https://www.divio.com/en/blog/documentation/
Some doctests executing code in the documentation has been added in #111, so this can be used as a guide for adding documentation doctests elsewhere. 

I have also looked a bit into adding doctests to the pymeasure code docstrings, but since most things are very interconnected and often depend on GUI features, I did not find feasible/sensible opportunities.

Resolving patch:
diff --git a/pymeasure/instruments/activetechnologies/AWG401x.py b/pymeasure/instruments/activetechnologies/AWG401x.py
--- a/pymeasure/instruments/activetechnologies/AWG401x.py
+++ b/pymeasure/instruments/activetechnologies/AWG401x.py
@@ -386,15 +386,9 @@ def beep(self):
     def save(self, position):
         """Save the actual configuration in memory.
 
-        Parameters
-        ----------
-        position : int
-            Instrument save position [0,4]
-
-        Raises
-        ------
-        ValueError
-            If position is outside permitted limit [0,4].
+        :param int position: Instrument save position [0,4]
+
+        :raises ValueError: If position is outside permitted limit [0,4].
         """
 
         if position >= 0 or position <= 4:
@@ -405,15 +399,9 @@ def save(self, position):
     def load(self, position):
         """Load the actual configuration in memory.
 
-        Parameters
-        ----------
-        position : int
-            Instrument load position [0,4]
+        :param int position: Instrument load position [0,4]
 
-        Raises
-        ------
-        ValueError
-            If position is outside permitted limit [0,4].
+        :raises ValueError: If position is outside permitted limit [0,4].
         """
 
         if position >= 0 or position <= 4:
diff --git a/pymeasure/instruments/hcp/tc038.py b/pymeasure/instruments/hcp/tc038.py
--- a/pymeasure/instruments/hcp/tc038.py
+++ b/pymeasure/instruments/hcp/tc038.py
@@ -70,22 +70,15 @@ class TC038(Instrument):
     application.
 
     The oven always responds with an "OK" to all valid requests or commands.
+
+    :param str adapter: Name of the COM-Port.
+    :param int address: Address of the device. Should be between 1 and 99.
+    :param int timeout: Timeout in ms.
     """
 
     def __init__(self, adapter, address=1, timeout=1000,
                  includeSCPI=False, **kwargs):
-        """
-        Initialize the communication.
-
-        Parameters
-        ----------
-        adapter : str
-            name COM-Port.
-        address : int
-            address of the device. Should be between 1 and 99.
-        timeout : int
-            Timeout in ms.
-        """
+
         super().__init__(adapter, "TC038", timeout=timeout,
                          write_termination="\r", read_termination="\r",
                          parity=Parity.even, **kwargs)


Test patch: