(self)
| 1515 | return "".join(p.render_docstring() + "\n" for p in params if p.docstring) |
| 1516 | |
| 1517 | def format_docstring(self) -> str: |
| 1518 | assert self.function is not None |
| 1519 | f = self.function |
| 1520 | # For the following special cases, it does not make sense to render a docstring. |
| 1521 | if f.kind in {METHOD_INIT, METHOD_NEW, GETTER, SETTER} and not f.docstring: |
| 1522 | return f.docstring |
| 1523 | |
| 1524 | # Enforce the summary line! |
| 1525 | # The first line of a docstring should be a summary of the function. |
| 1526 | # It should fit on one line (80 columns? 79 maybe?) and be a paragraph |
| 1527 | # by itself. |
| 1528 | # |
| 1529 | # Argument Clinic enforces the following rule: |
| 1530 | # * either the docstring is empty, |
| 1531 | # * or it must have a summary line. |
| 1532 | # |
| 1533 | # Guido said Clinic should enforce this: |
| 1534 | # http://mail.python.org/pipermail/python-dev/2013-June/127110.html |
| 1535 | |
| 1536 | lines = f.docstring.split('\n') |
| 1537 | if len(lines) >= 2: |
| 1538 | if lines[1]: |
| 1539 | fail(f"Docstring for {f.full_name!r} does not have a summary line!\n" |
| 1540 | "Every non-blank function docstring must start with " |
| 1541 | "a single line summary followed by an empty line.") |
| 1542 | elif len(lines) == 1: |
| 1543 | # the docstring is only one line right now--the summary line. |
| 1544 | # add an empty line after the summary line so we have space |
| 1545 | # between it and the {parameters} we're about to add. |
| 1546 | lines.append('') |
| 1547 | |
| 1548 | # Fail if the summary line is too long. |
| 1549 | # Warn if any of the body lines are too long. |
| 1550 | # Existing violations are recorded in OVERLONG_{SUMMARY,BODY}. |
| 1551 | max_width = f.docstring_line_width |
| 1552 | summary_len = len(lines[0]) |
| 1553 | max_body = max(map(len, lines[1:])) |
| 1554 | if summary_len > max_width: |
| 1555 | if not self.permit_long_summary: |
| 1556 | fail(f"Summary line for {f.full_name!r} is too long!\n" |
| 1557 | f"The summary line must be no longer than {max_width} characters.") |
| 1558 | else: |
| 1559 | if self.permit_long_summary: |
| 1560 | warn("Remove the @permit_long_summary decorator from " |
| 1561 | f"{f.full_name!r}!\n") |
| 1562 | |
| 1563 | if max_body > max_width: |
| 1564 | if not self.permit_long_docstring_body: |
| 1565 | warn(f"Docstring lines for {f.full_name!r} are too long!\n" |
| 1566 | f"Lines should be no longer than {max_width} characters.") |
| 1567 | else: |
| 1568 | if self.permit_long_docstring_body: |
| 1569 | warn("Remove the @permit_long_docstring_body decorator from " |
| 1570 | f"{f.full_name!r}!\n") |
| 1571 | |
| 1572 | parameters_marker_count = len(f.docstring.split('{parameters}')) - 1 |
| 1573 | if parameters_marker_count > 1: |
| 1574 | fail('You may not specify {parameters} more than once in a docstring!') |
no test coverage detected