2

I wrote several Python 3 modules of the following format:

def some_module():
'''Do something.

Parameters
----------
Returns
-------
'''
# Some code

When I run PyLint or PyLint3 over the file, I get the following error:

************* Module some_module.some_module
C: 1, 0: Missing module docstring (missing-docstring)

What am I doing wrong? Does PyLint require a specific docstring style?

Karl Knechtel
  • 62,466
  • 11
  • 102
  • 153
  • 4
    Your example is a function docstring, pylint asks you to document the module itself. – Norrius Jul 20 '19 at 00:05
  • As I understand from [this question](https://stackoverflow.com/questions/48878730/what-is-the-difference-between-python-function-and-python-module), functions contain reusable code for specific tasks, while modules are bundles of functions, classes etc. But in this case, all modules consist of only a single function, so there is no need for a module-level docstring. Is PyLint able to understand this? Or should even simple functions have both a module and a function docstring? Or should I avoid creating too many functions and rather bundle them into modules? –  Jul 20 '19 at 14:30
  • Also, from [this](https://stackoverflow.com/questions/2557110/what-to-put-in-a-python-module-docstring) discussion it's not clear what differentiates function docstrings from module docstrings. Could it be that PEP 8 and PEP 257 are only relevant for the organization of large projects and have only limited value for small scripts? –  Jul 20 '19 at 14:45
  • 1
    Put simply, modules are .py files. Pylint doesn't really "understand" anything, it simply checks (statically) your code against a bunch of rules. In particular, `missing-docstring` checks that modules, classes and functions have docstrings (i.e. `__doc__`). Whether you want to enforce these rules or not is up to you. For example, I've found `too-few-public-methods` to be pretty useless, so I usually disable it. – Norrius Jul 20 '19 at 14:47
  • Ok, I see. Thanks! –  Jul 20 '19 at 15:40
  • Does this answer your question? [How do you fix "Missing module docstringpylint(missing-module-docstring)"](https://stackoverflow.com/questions/65949325/how-do-you-fix-missing-module-docstringpylintmissing-module-docstring) – Karl Knechtel Feb 04 '23 at 09:20

1 Answers1

4

Have you tried indenting the doc-string, so it identified as part of the module?

def some_module():
    '''Do something.

    Parameters
    ----------
    Returns
    -------
    '''
    # Some code
    ...
Zak
  • 12,213
  • 21
  • 59
  • 105