Documentation improvements #2314
Conversation
docs/api.rst
Outdated
| forms, and the first of them is a string literal, this string becomes the | ||
| :term:`py:docstring` of the function. The final body form is implicitly | ||
| returned; thus, ``(defn f [] 5)`` is equivalent to ``(defn f [] (return | ||
| 5))``. By contrast, the ``defn`` form itself always returns ``None``. |
There was a problem hiding this comment.
What does "the defn form itself" mean? I'm not quite sure what you're trying to get at here.
There was a problem hiding this comment.
(defn f [] 3) returns None, whereas (f) returns 3.
There was a problem hiding this comment.
Hmm... I feel like explaining that distinction only serves to confuse more than elucidate, personally.
There was a problem hiding this comment.
It seems that the return value of defn has to be documented somewhere, particularly since it's a chief difference from fn. If you don't think this is the right way to document it, what do you think is the right way?
There was a problem hiding this comment.
We don't have any documentation for setv saying it evaluates to None, only that setx is the "expression" form of setv; I think we can document defn/fn similarly.
If you feel strongly that we should mention it though, I think it'll be less confusing up near the top, a la something like the following:
``defn`` compiles to a :ref:`function definition <py:function>` (or possibly
to an assignment of a :ref:`lambda expression <py:lambda>`). Unlike ``fn`` however,
the ``defn`` form itself evaluates to ``None``. It requires two arguments...
There was a problem hiding this comment.
We don't have any documentation for
setvsaying it evaluates toNone
We absolutely should. setv is among the many core macros whose documentation needs a rewrite.
If you feel strongly that we should mention it though, I think it'll be less confusing up near the top
Okay, how's this?
Fixes #2313.