16f6c0aecf
Inline adoc files when they are included exactly once. Also fix language tags because this inlining gives us better information on what language the code is written in.
39 lines
955 B
Plaintext
39 lines
955 B
Plaintext
== Why is this an issue?
|
|
|
|
A string literal that is the first statement in a module, function, class, or method is a docstring. A docstring should document what a caller needs to know about the code. Information about what it does, what it returns, and what it requires are all valid candidates for documentation. Well written docstrings allow callers to use your code without having to first read it and understand its logic.
|
|
|
|
|
|
By convention, docstrings are enclosed in three sets of double-quotes.
|
|
|
|
|
|
=== Noncompliant code example
|
|
|
|
[source,python]
|
|
----
|
|
def my_function(a,b):
|
|
----
|
|
|
|
|
|
=== Compliant solution
|
|
|
|
[source,python]
|
|
----
|
|
def my_function(a,b):
|
|
"""Do X"""
|
|
----
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
=== Message
|
|
|
|
Add a docstring to this [module|function|class|method].
|
|
|
|
The docstring for this [module|function|class|method] should not be empty.
|
|
|
|
|
|
endif::env-github,rspecator-view[]
|