Documentation changes to coding module.

Author: emes4

src/doc/en/reference/coding/index.rst

@@ -7,16 +7,13 @@ Coding theory is the mathematical theory for algebraic and combinatorial codes
 used for forward error correction in communications theory. Sage provides an
 extensive library of objects and algorithms in coding theory.
 
-Basic objects in coding theory are channels, codes, linear codes, encoders, and
+Basic objects in coding theory are codes, channels, encoders, and
 decoders. The following modules provide the base classes defining them.
 
 .. toctree::
    :maxdepth: 1
 
    sage/coding/abstract_code
-   sage/coding/linear_code_no_metric
-   sage/coding/linear_code
-   sage/coding/linear_rank_metric
    sage/coding/channel
    sage/coding/encoder
    sage/coding/decoder
@@ -33,8 +30,28 @@ the parameters of linear codes are provided.
    sage/coding/encoders_catalog
    sage/coding/bounds_catalog
 
-Families of Codes
------------------
+
+Linear Codes
+------------
+
+The following module is a base class for linear code objects regardless their
+metric.
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/coding/linear_code_no_metric
+
+There is a number of representatives of linear codes over a specific metric.
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/coding/linear_code
+   sage/coding/linear_rank_metric
+
+Families of Linear Codes
+------------------------
 
 Famous families of codes, listed below, are represented in Sage by their own
 classes. For some of them, implementations of special decoding algorithms or

src/sage/coding/abstract_code.py

@@ -1,9 +1,41 @@
 r"""
-Base class for Codes
+Codes
 
 Class supporting methods available for any type of code (linear, non-linear) and
 over any metric (Hamming, rank).
 
+There are further abstract classes representing certain types of codes. For
+linear codes,
+:class:`~sage.coding.linear_code_no_metric.AbstractLinearCodeNoMetric` contains
+all the methods that any linear code can use regardless of its metric.
+Inheriting from this class are base classes for linear codes over specific
+metrics. For example, :class:`~sage.coding.linear_code.AbstractLinearCode` is a
+base class for all linear codes over the Hamming metric.
+
+Take the class :class:`~sage.coding.hamming_code.HammingCode`. This
+class inherits from :class:`~sage.coding.linear_code.AbstractLinearCode`, since
+it is a linear code over the Hamming metric.
+:class:`~sage.coding.linear_code.AbstractLinearCode` then inherits from
+:class:`~sage.coding.linear_code_no_metric.AbstractLinearCodeNoMetric`, since it
+is a linear code. Finally, this class inherits from
+:class:`~sage.coding.abstract_code.AbstractCode`, since it is a code.
+
+
+The following diagram shows the inheritance relationship in the coding module::
+
+    AbstractCode
+    + AbstractLinearCodeNoMetric
+    | + AbstractLinearCode
+    | | + ParityCheckCode
+    | | + HammingCode
+    | | + CyclicCode
+    | | + BCHCode
+    | | + GolayCode
+    | | + ReedMullerCode
+    | | + GeneralizedReedSolomonCode
+    | | + GoppaCode
+    | + AbstractLinearRankMetricCode
+
 Any class inheriting from AbstractCode can use the encode/decode framework.
 
 The encoder/decoder framework within the coding module offers the creation and

src/sage/coding/linear_code.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 r"""
-Linear codes
+Generic structures for linear codes over the Hamming metric
 
 Linear Codes
 ============