I just don´t understand why in the first line I should begin intermediately
after “””
Conventions such as these enable external tools to operate on your
docstring and make certain assumptions, such as what types arguments expect
and their description. The first line is typically reserved for a summary
of the docstring, and having it on the first line provides two advantages
that, aside from tools, I sometimes benefit from myself.
1. Easy access, always the first line. (See example below)
2. Perhaps more importantly, it visually prohibits the summary from
taking up multiple lines, as the next line would have a different
indentation due to the “””
def my_function():
"""First line
Subsequent lines
are here.
"""
summary = my_function.__doc__.split("\n")[0]
print(summary)
# Try putting the summary on the next line
Some tools assume the first line is your summary (such as Sphinx), but if
you aren’t using those tools or making tools yourself that depend on this
convention, it probably isn’t the end of the world if you go with what you
prefer.
Speaking of preference, tools such as Sphinx and docstring conventions,
there is another player on the block that I personally prefer.
- Napoleon
<https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>
The important bit I think is that you find something you like that (1)
remains consistent, (2) isn’t entirely alien to others (like us) if you
want others to read it and (3) works with the tools you would like to use,
such as Sphinx.
--
You received this message because you are subscribed to the Google Groups
"Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/python_inside_maya/CAFRtmODfYsvKxcfkeHY6Qo61tU052xigvd6C6RWD4mxJXUQJkQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
