Skip to content

Commit

Permalink
gh-38117: Add small examples of common docstring styles
Browse files Browse the repository at this point in the history
    
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes #12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes #12345". -->

which I think are already established.  But it is good to recommend
preferred styles to keep docstrings in consistent styles.

motivated by the comment:
#37821 (comment)

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [x] I have updated the documentation and checked the documentation
preview.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->

#38068 (merged here)
    
URL: #38117
Reported by: Kwankyu Lee
Reviewer(s): gmou3, Kwankyu Lee
  • Loading branch information
Release Manager committed Jun 7, 2024
2 parents eac0fc5 + f4cb7cb commit e6c4f20
Showing 1 changed file with 19 additions and 13 deletions.
32 changes: 19 additions & 13 deletions src/doc/en/developer/coding_basics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -254,14 +254,14 @@ The top of each Sage code file should follow this format::

AUTHORS:

- YOUR NAME (2005-01-03): initial version

- person (date in ISO year-month-day format): short desc
- Your Name (2024-01-13): initial version
- Alice Liddell (2024-05-31): added a method; cleaned docstrings
- Full name (YYYY-MM-DD): short description

"""

# ****************************************************************************
# Copyright (C) 2013 YOUR NAME <your email>
# Copyright (C) 2024 Your Name <your email>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
Expand Down Expand Up @@ -341,9 +341,9 @@ information. You can use the existing functions of Sage as templates.

The INPUT block describes all arguments that the function accepts.

1. The type names should be descriptive, but do not have to represent
the exact Sage/Python types. For example, use "integer" for
anything that behaves like an integer, rather than ``int``.
1. The type names should be descriptive, but do not have to represent the
exact Sage/Python types. For example, use "integer" for anything that
behaves like an integer, rather than "int" or "Integer".

2. Mention the default values of the input arguments when applicable.

Expand All @@ -353,7 +353,13 @@ information. You can use the existing functions of Sage as templates.
- ``n`` -- integer
- ``p`` -- prime integer (default: `2`); coprime with ``n``
- ``p`` -- prime integer (default: `2`); coprime with `n`
- ``var`` -- string (default: ``'lambda'``)
- ``check`` -- boolean (default: ``True``); specifies whether to check for primality
- ``algorithm`` -- (default: ``None``) the name of the algorithm to use
The OUTPUT block describes the expected output. This is required if the
one-sentence description of the function needs more explanation.
Expand Down Expand Up @@ -653,12 +659,12 @@ indentation:
INPUT:
- ``x`` -- integer (default: ``1``); the description of the
- ``x`` -- integer (default: `1`); the description of the
argument ``x`` goes here. If it contains multiple lines, all
the lines after the first need to begin at the same indentation
as the backtick.
- ``y`` -- integer (default: ``2``); the description of the
- ``y`` -- integer (default: `2`); the description of the
argument ``y``
OUTPUT: tuple; further description of the output
Expand All @@ -669,7 +675,7 @@ indentation:
sage: A = EuclideanSpace(2)
sage: A.point(2, 3)
(32, 3)
(2, 3)
We now ... ::
Expand All @@ -686,7 +692,7 @@ indentation:
.. NOTE::
This function uses :func:`pow` to determine the fifth
power of ``x``.
power of `x`.
...
Expand All @@ -696,7 +702,7 @@ indentation:
TESTS::
sage: A.point(42, 0) # Check for corner case y = 0
sage: A.point(42, 0) # check for corner case y = 0
...
"""
<body of the function>
Expand Down

0 comments on commit e6c4f20

Please sign in to comment.