Help formatting cuts off multi-line doc strings

[steven-cutting]

What

If there is more than one line in a doc string of a function that is used to create a command. All but the first line are lost.

Example

from face import Command

def multi_line_doc():
    """
    Some multi line doc string. Some multi line doc string. Some multi line doc string. Some multi line doc string.

    Some multi line doc string. Some multi line doc string. Some multi line doc string. Some multi line doc string.
    """
    return

cmd = Command(multi_line_doc, 'cmd')
cmd.run(argv=['example.py', '--help'])

This results in:

Usage: example.py [FLAGS] 

Some multi line doc string. Some multi line doc string. Some multi line doc string. Some multi line doc string.


Flags: 

  --help / -h   show this help message and exit

---

Is this desired, or something that can be changed.
If it is desired, should an error be raised?

Let me know what you think and I can take care of it.

[mahmoud]

Ah, this might be partially intentional. At least with the case of subcommand descriptions, I recall only pulling the first paragraph to keep things from getting out of hand in the subcommand listing. It should be noted that the text in question can always be manually set via the doc kwarg when calling add().

I've always thought of the docstring as more of a reasonable and convenient better-than-nothing default than a critical part of the API. What do you think?