From d29a5d4751731b1afc324eb40f9ee5d268d7acb4 Mon Sep 17 00:00:00 2001
From: Adnan Hemani <adnan.h@berkeley.edu>
Date: Sat, 28 Jan 2023 23:15:52 -0800
Subject: [PATCH] Fix documentation

---
 datascience/tables.py | 40 +++++++++++++++++++++++++++++++++++++---
 datascience/util.py   |  2 +-
 docs/tables.rst       |  6 ------
 3 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/datascience/tables.py b/datascience/tables.py
index 776c78bb..b45c8dd7 100644
--- a/datascience/tables.py
+++ b/datascience/tables.py
@@ -288,6 +288,7 @@ def num_rows(self):
             integer value stating number of rows
 
         Example:
+
         >>> t = Table().with_columns({
         ...     'letter': ['a', 'b', 'c', 'z'],
         ...     'count':  [  9,   3,   3,   1],
@@ -307,6 +308,7 @@ def rows(self):
             list-like Rows object that contains tuple-like Row objects
 
         Example:
+
         >>> t = Table().with_columns({
         ...     'letter': ['a', 'b', 'c', 'z'],
         ...     'count':  [  9,   3,   3,   1],
@@ -322,7 +324,12 @@ def rows(self):
         return self.Rows(self)
 
     def row(self, index):
-        """Return a row."""
+        """
+        Return a row.
+
+        Please see extended docstring at https://github.com/data-8/datascience/blob/614db00e7d22e52683860d2beaa4037bec26cf87/datascience/tables.py#L5673-L5765
+        for how to interact with Rows.
+        """
         return self.rows[index]
 
     @property
@@ -334,6 +341,7 @@ def labels(self):
             tuple of labels
 
         Example:
+        
         >>> t = Table().with_columns({
         ...     'letter': ['a', 'b', 'c', 'z'],
         ...     'count':  [  9,   3,   3,   1],
@@ -358,6 +366,7 @@ def columns(self):
             tuple of columns
 
         Example:
+
         >>> t = Table().with_columns({
         ...     'letter': ['a', 'b', 'c', 'z'],
         ...     'count':  [  9,   3,   3,   1],
@@ -418,6 +427,23 @@ def values(self):
         If all columns are the same dtype, the resulting array
         will have this dtype. If there are >1 dtypes in columns,
         then the resulting array will have dtype `object`.
+
+        Example:
+
+        >>> tiles = Table().with_columns(
+        ...     'letter', make_array('c', 'd'),
+        ...     'count',  make_array(2, 4),
+        ... )
+        >>> tiles.values
+        array([['c', 2],
+           ['d', 4]], dtype=object)
+        >>> t = Table().with_columns(
+        ...     'col1', make_array(1, 2),
+        ...     'col2', make_array(3, 4),
+        ... )
+        >>> t.values
+        array([[1, 3],
+           [2, 4]])
         """
         dtypes = [col.dtype for col in self.columns]
         if len(set(dtypes)) > 1:
@@ -437,6 +463,7 @@ def column_index(self, label):
             integer value specifying the index of the column label
 
         Example:
+
         >>> t = Table().with_columns({
         ...     'letter': ['a', 'b', 'c', 'z'],
         ...     'count':  [  9,   3,   3,   1],
@@ -519,6 +546,7 @@ def first(self, label):
             zeroth item of column
 
         Example:
+
         >>> t = Table().with_columns({
         ...     'letter': ['a', 'b', 'c', 'z'],
         ...     'count':  [  9,   3,   3,   1],
@@ -540,6 +568,7 @@ def last(self, label):
             last item of column
 
         Example:
+
         >>> t = Table().with_columns({
         ...     'letter': ['a', 'b', 'c', 'z'],
         ...     'count':  [  9,   3,   3,   1],
@@ -2283,7 +2312,7 @@ def sample(self, k=None, with_replacement=True, weights=None):
 
     def shuffle(self):
         """Return a new table where all the rows are randomly shuffled from the
-        original table..
+        original table.
 
         Returns:
             A new instance of ``Table`` with all ``k`` rows shuffled.
@@ -4674,7 +4703,12 @@ def _split_column_and_labels(self, column_or_label):
 
     # Deprecated
     def pivot_hist(self, pivot_column_label, value_column_label, overlay=True, width=6, height=4, **vargs):
-        """Draw histograms of each category in a column. (Deprecated)"""
+        """
+        Draw histograms of each category in a column. (Deprecated)
+
+        Recommended: Use hist(value_column_label, group=pivot_column_label), or with side_by_side=True if you really want side-by-side bars.
+
+        """
         warnings.warn("pivot_hist is deprecated; use "
                       "hist(value_column_label, group=pivot_column_label), or "
                       "with side_by_side=True if you really want side-by-side "
diff --git a/datascience/util.py b/datascience/util.py
index 9bc9d34c..b1289972 100644
--- a/datascience/util.py
+++ b/datascience/util.py
@@ -249,7 +249,7 @@ def objective(args):
         return result.x
 
 def is_non_string_iterable(value):
-    """Whether a value is iterable."""
+    """Returns a boolean value representing whether a value is iterable."""
     if isinstance(value, str):
         return False
     if hasattr(value, '__iter__'):
diff --git a/docs/tables.rst b/docs/tables.rst
index 0198baef..285ce714 100644
--- a/docs/tables.rst
+++ b/docs/tables.rst
@@ -31,18 +31,12 @@ But these are not valid::
 If that syntax is confusing, you can click the method name itself to get to the
 details page for that method. That page will have a more straightforward syntax.
 
-At the time of this writing, most methods only have one or two sentences of
-documentation, so what you see here is all that you'll get for the time being.
-We are actively working on documentation, prioritizing the most complicated
-methods (mostly visualizations).
-
 Creation
 
 .. autosummary::
     :toctree: _autosummary
 
     Table.__init__
-    Table.empty
     Table.from_records
     Table.from_columns_dict
     Table.read_table