Fix documentation for gensim.corpora. Partial fix #1671

gensim/corpora/bleicorpus.py

@@ -5,7 +5,7 @@
 # Licensed under the GNU LGPL v2.1 - http://www.gnu.org/licenses/lgpl.html
 
 
-"""Blei's LDA-C format."""
+"""Сorpus in Blei's LDA-C format."""
 
 from __future__ import with_statement
 
@@ -17,7 +17,7 @@
 from six.moves import xrange
 
 
-logger = logging.getLogger('gensim.corpora.bleicorpus')
+logger = logging.getLogger(__name__)
 
 
 class BleiCorpus(IndexedCorpus):
@@ -28,24 +28,22 @@ class BleiCorpus(IndexedCorpus):
 
     Each document is one line::
 
-      N fieldId1:fieldValue1 fieldId2:fieldValue2 ... fieldIdN:fieldValueN
+        N fieldId1:fieldValue1 fieldId2:fieldValue2 ... fieldIdN:fieldValueN
 
-    The vocabulary is a file with words, one word per line; word at line K has an
-    implicit ``id=K``.
+
+    The vocabulary is a file with words, one word per line; word at line K has an implicit `id=K`.
 
     """
 
     def __init__(self, fname, fname_vocab=None):
         """
-        Initialize the corpus from a file.
 
         Parameters
         ----------
         fname : str
-            Serialized corpus's filename.
-        fname_vocab : str or None, optional
-            Vocabulary file. If not given, searching for the
-            vocab/vocab.txt file.
+            File path to Serialized corpus.
+        fname_vocab : str, optional
+            Vocabulary file. If `fname_vocab` is None, searching for the vocab.txt or `fname_vocab`.vocab file.
 
         Raises
         ------
@@ -76,25 +74,32 @@ def __init__(self, fname, fname_vocab=None):
         self.id2word = dict(enumerate(words))
 
     def __iter__(self):
-        """Iterate over the corpus, returning one sparse vector at a time."""
+        """Iterate over the corpus, returning one sparse (BoW) vector at a time.
+
+        Yields
+        ------
+        list of (int, float)
+            Document's BoW representation.
+
+        """
         lineno = -1
         with utils.smart_open(self.fname) as fin:
             for lineno, line in enumerate(fin):
                 yield self.line2doc(line)
         self.length = lineno + 1
 
     def line2doc(self, line):
-        """Convert line to document.
+        """Convert line in Blei LDA-C format to document (BoW representation).
 
         Parameters
         ----------
         line : str
-            Document's string representation.
+            Line in Blei's LDA-C format.
 
         Returns
         -------
         list of (int, float)
-            Document's list representation.
+            Document's BoW representation.
 
         """
         parts = utils.to_unicode(line).split()
@@ -108,23 +113,25 @@ def line2doc(self, line):
     def save_corpus(fname, corpus, id2word=None, metadata=False):
         """Save a corpus in the LDA-C format.
 
-        There are actually two files saved: `fname` and `fname.vocab`, where
-        `fname.vocab` is the vocabulary file.
+        Notes
+        -----
+        There are actually two files saved: `fname` and `fname.vocab`, where `fname.vocab` is the vocabulary file.
 
         Parameters
         ----------
         fname : str
-            Filename.
-        corpus : iterable
-            Iterable of documents.
+            Path to output filename.
+        corpus : iterable of iterable of (int, float)
+            Input corpus
         id2word : dict of (str, str), optional
-            Transforms id to word.
-        metadata : bool
-            Any additional info.
+            Mapping id -> word for `corpus`.
+        metadata : bool, optional
+            THIS PARAMETER WILL BE IGNORED.
 
         Returns
         -------
         list of int
+            Offsets for each line in file (in bytes).
 
         """
         if id2word is None:
@@ -153,16 +160,18 @@ def save_corpus(fname, corpus, id2word=None, metadata=False):
         return offsets
 
     def docbyoffset(self, offset):
-        """Return document corresponding to `offset`.
+        """Get document corresponding to `offset`,
+        offset can be given from :meth:`~gensim.corpora.bleicorpus.BleiCorpus.save_corpus`.
 
         Parameters
         ----------
         offset : int
-            Position of the document in the file.
+            Position of the document in the file (in bytes).
 
         Returns
         -------
         list of (int, float)
+            Document in BoW format.
 
         """
         with utils.smart_open(self.fname) as f: