Diferències

Ací es mostren les diferències entre la revisió seleccionada i la versió actual de la pàgina.

Enllaç a la visualització de la comparació

--- info:cursos:pue:python-pcpp1:m2:4.1 [14/12/2023 12:15] – mate
+++ info:cursos:pue:python-pcpp1:m2:4.1 [19/12/2023 11:02] (actual) – [One-line docstrings] mate
@@ Línia 140: / Línia 140: @@
     return (x+y) * 0.25
 </code>
+=== Multi-line docstrings
+Multi-line docstrings should be used for non-obvious cases and more detailed descriptions of code segments. They should have a summary line, similar to what a one-line docstring looks like, followed by a blank line and a more elaborate description. The summary line may be located on the same line as the open triple double quotes, or put on the next line. The end quotes should be put on a separate line.
+Important notes:
+  * a multi-line docstring should be indented to the same level as the open quotes, for example:
+<code python>
+def king_creator(name="Greg", ordinal="I", country="Neverland"):
+    """Create a king following the article title naming convention.
+    Keyword arguments:
+    :arg name: the king's name (default: Greg)
+    :type name: str
+    :arg ordinal: Roman ordinal number (default: I)
+    :type ordinal: str
+    :arg country: the country ruled (default: Neverland)
+    :type country: str
+    """
+    if name == "Voldemort":
+        return "Voldemort is a reserved name."
+    ...
+</code>
+  * you should insert a blank line after all the multi-line docstrings that are documenting a class;
   * script docstrings (in the sense of stand-alone programs/single file executables) should document the script's function, command line syntax, environment variables, and files. The description should be balanced in a way that it helps new users understand the script's usage, as well as provide a quick reference to all the program's features for the more experienced user;
   * module docstrings should list the classes, exceptions, and functions exported by the module;