Doc updates (#1297)

First part of an unknown number of rounds of documentation review.

Author: rocky

mathics/builtin/arithmetic.py

@@ -627,7 +627,7 @@ class I_(Predefined, SympyObject):
     name = "I"
     sympy_name = "I"
     sympy_obj = sympy.I
-    summary_text = "imaginary unit"
+    summary_text = "imaginary unit number Sqrt[-1]"
     python_equivalent = 1j
 
     def is_constant(self) -> bool:
@@ -658,7 +658,7 @@ class Im(SympyFunction):
      = -Graphics-
     """
 
-    summary_text = "imaginary part"
+    summary_text = "imaginary part of a complex number"
     attributes = A_LISTABLE | A_NUMERIC_FUNCTION | A_PROTECTED
 
     def eval_complex(self, number, evaluation: Evaluation):
@@ -817,10 +817,14 @@ class Re(SympyFunction):
      = -Graphics-
     """
 
-    summary_text = "real part"
+    summary_text = "real part of a complex number"
     attributes = A_LISTABLE | A_NUMERIC_FUNCTION | A_PROTECTED
     sympy_name = "re"
 
+    def eval(self, number, evaluation: Evaluation):
+        "Re[number_]"
+        return from_sympy(sympy.re(number.to_sympy().expand(complex=True)))
+
     def eval_complex(self, number, evaluation: Evaluation):
         "Re[number_Complex]"
         if isinstance(number, Complex):
@@ -831,10 +835,6 @@ def eval_number(self, number, evaluation: Evaluation):
 
         return number
 
-    def eval(self, number, evaluation: Evaluation):
-        "Re[number_]"
-        return from_sympy(sympy.re(number.to_sympy().expand(complex=True)))
-
 
 class Real_(Builtin):
     """
@@ -987,8 +987,8 @@ class Sum(IterationFunction, SympyFunction):
         }
     )
 
-    def get_result(self, items):
-        return Expression(SymbolPlus, *items)
+    def get_result(self, elements) -> Expression:
+        return Expression(SymbolPlus, *elements)
 
     def to_sympy(self, expr, **kwargs) -> Optional[SympyExpression]:
         """

mathics/builtin/files_io/importexport.py

@@ -1327,7 +1327,7 @@ class Import(Builtin):
       <dd>imports the specified elements from a file.
 
       <dt>'Import["$file$", {"$fmt$", $elements$}]'
-      <dd>imports the specified elements from a file asuming the specified file format.
+      <dd>imports the specified elements from a file assuming the specified file format.
 
       <dt>'Import["http://$url$", ...]' and 'Import["ftp://$url$", ...]'
       <dd>imports from a URL.

mathics/builtin/functional/apply_fns_to_lists.py

@@ -173,21 +173,21 @@ class MapAt(Builtin):
       <dd>applies $f$ to the part of $expr$ at position {$i$, $j$, ...}.
 
       <dt>'MapAt[$f$, $pos$]'
-      <dd>represents an operator form of MapAt that can be applied to an expression.
+      <dd>represents an operator form of 'MapAt' that can be applied to an expression.
     </dl>
 
     Map function $f$ to the second element of an simple flat list:
     >> MapAt[f, {a, b, c}, 2]
      = {a, f[b], c}
 
-    Above we specified a simple integer value 2. In general, the expression can an arbitrary vector.
+    Above, we specified a simple integer value 2. In general, the expression can an arbitrary vector.
 
     Using 'MapAt' with 'Function[0]', we can zero a value or values in a vector:
 
     >> MapAt[0&, {{1, 1}, {1, 1}}, {2, 1}]
      = {{1, 1}, {0, 1}}
 
-    When the dimension of the replacment expression is less than the vector, \
+    When the dimension of the replacement expression is less than the vector, \
     that element's dimension changes:
 
     >> MapAt[0&, {{0, 1}, {1, 0}}, 2]
@@ -396,7 +396,7 @@ class Scan(Builtin):
       <dt>'Scan[$f$, $expr$]'
       <dd>applies $f$ to each element of $expr$ and returns 'Null'.
 
-      <dt>'Scan[$f$, $expr$, $levelspec$]
+      <dt>'Scan[$f$, $expr$, $levelspec$]'
       <dd>applies $f$ to each level specified by $levelspec$ of $expr$.
     </dl>
 

mathics/builtin/testing_expressions/equality_inequality.py

@@ -349,7 +349,7 @@ class Between(Builtin):
       <dt>'Between'[$x$, {$min$, $max$}]
       <dd>equivalent to $min$ <= $x$ <= $max$.
       <dt>'Between[$x$, { {$min1$, $max1$}, {$min2$, $max2$}, ...]'
-      <dd>equivalent to $min1$ <= $x$ <= $max1$' || $min2$ <= $x$ <= $max2$ ...
+      <dd>equivalent to $min1$ <= $x$ <= $max1$ || $min2$ <= $x$ <= $max2$ ...
       <dt>'Between[$range$]'
       <dd>operator form that yields 'Between'[$x$, $range$] when applied to expression $x$.
     </dl>

mathics/builtin/trace.py

@@ -153,7 +153,7 @@ class Stacktrace(_TraceBase):
 
     <dl>
       <dt>'Stacktrace[]'
-      <dd>Print Mathics3 stack trace of evalutations leading to this point
+      <dd>Print Mathics3 stack trace of evaluations leading to this point
     </dl>
 
     To show the Mathics3 evaluation stack at the \

mathics/core/builtin.py

@@ -933,7 +933,7 @@ class IterationFunction(Builtin, ABC):
     allow_loopcontrol = False
     throw_iterb = True
 
-    def get_result(self, elements) -> ListExpression:
+    def get_result(self, elements) -> Expression:
         raise NotImplementedError
 
     def eval_symbol(self, expr, iterator, evaluation):