two comments, no functional changes

papers/__main__.py

@@ -1,4 +1,4 @@
-"""That is the script called by papers
+"""That is the script called by the papers cli command.
 """
 import os
 import sys
@@ -31,6 +31,9 @@ def check_legacy_config(configfile):
 
 
 def get_biblio(config):
+ """
+ Given a config, get the Biblio object associated with this run. If there's no Biblio object, will make a new one, silently.
+ """
  if config.bibtex is None:
  raise ValueError('bibtex is not initialized')
  relative_to = os.path.sep if config.absolute_paths else (os.path.dirname(config.bibtex) if config.bibtex else None)
@@ -408,7 +411,7 @@ def check_install(parser, o, config):
 
 def addcmd(parser, o, config):
  """
- Given an options set and a config, sets up the function call to add the file or dir to the bibtex, and executes it.
+ Given an options set and a config, sets up the function call to add the file or all files in the directory to the bibtex, and executes it.
  """
 
  set_nameformat_config_from_cmd(o, config)
@@ -471,6 +474,9 @@ def addcmd(parser, o, config):
  savebib(biblio, config)
 
 def checkcmd(parser, o, config):
+ """
+ Loops over the entire bib file that the Papers install sees, and checks each entry for formatting and for the existance of duplicates. Then writes the Biblio object back to your Bibtex file.
+ """
  set_keyformat_config_from_cmd(o, config)
 
  biblio = get_biblio(config)
@@ -930,7 +936,7 @@ def get_parser(config=None):
 
  # list
  # ======
- listp = subparsers.add_parser('list', description='list (a subset of) entries',
+ listp = subparsers.add_parser('list', description='list (a subset of) entries in the existing bib file.',
  parents=[cfg])
 
  listp.add_argument('fullsearch', nargs='*', help='''Search field. Usually no quotes required. See keywords to search specific fields. All words must find a match, unless --any is passed.''')
@@ -1105,4 +1111,4 @@ class PapersExit(Exception):
  try:
  main()
  except PapersExit:
- sys.exit(1)
+ sys.exit(1)

papers/bib.py

@@ -198,7 +198,7 @@ class DuplicateKeyError(ValueError):
 
 class Biblio:
  """
- main config
+ The bibtex object that we operate on, which is mainly used to read and write to dynamically, and can then send the changes to be stored in a specified bibtex file on disk.
  """
  def __init__(self, db=None, filesdir=None, key_field='ID', nameformat=NAMEFORMAT, keyformat=KEYFORMAT, similarity=DEFAULT_SIMILARITY, relative_to=None):
  """
@@ -591,6 +591,9 @@ def rename_entries_files(self, copy=False, relative_to=None):
  def fix_entry(self, e, fix_doi=True, fetch=False, fetch_all=False,
  fix_key=False, auto_key=False, key_ascii=False, encoding=None,
  format_name=True, interactive=False):
+ """
+ Given an entry in an existing Bilio object, checks the format name and encoding. Will fetch additional info if it's missing.
+ """
 
  e_old = e.copy()
 
@@ -713,6 +716,9 @@ def entry_filecheck_metadata(e, file, image=False):
 
 def entry_filecheck(e, delete_broken=False, fix_mendeley=False,
  check_hash=False, check_metadata=False, interactive=True, image=False, relative_to=None):
+ """
+ Checks the bib entry file actually corresponds to an existing, correct file on disk.
+ """
 
  if 'file' not in e:
  return
@@ -786,4 +792,4 @@ def entry_filecheck(e, delete_broken=False, fix_mendeley=False,
 
  newfiles.append(file)
 
- e['file'] = format_file(newfiles, relative_to=relative_to)
+ e['file'] = format_file(newfiles, relative_to=relative_to)

tests/__init__.py

@@ -2,4 +2,4 @@
 # setup user name and user email if not set (otherwise commit will fail)
 sp.check_call('git config --list | grep user.name || git config --global user.name "Papers Tests"', shell=True)
 sp.check_call('git config --list | grep user.email || git config --global user.email "[email protected]"', shell=True)
-del sp
+del sp