From ecfd737fb906d863f93c0425abb07603a6b3883d Mon Sep 17 00:00:00 2001 From: Christopher Allan Webber Date: Sun, 23 Feb 2014 15:20:43 -0600 Subject: [PATCH] Document how to supply docstrings to classes and class methods / lambdas We want to encourage good practice, documentation-wise, amongst Hy users! --- docs/language/api.rst | 16 ++++++++++++++++ docs/tutorial.rst | 16 ++++++++++++---- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/language/api.rst b/docs/language/api.rst index 2e30ab4..02823a1 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -814,6 +814,22 @@ function is defined and passed to another function for filtering output. Alice Dave +Just as in normal function definitions, if the first element of the +body is a string, it serves as docstring. This is useful for giving +class methods docstrings. + + => (setv times-three + ... (fn [x] + ... "Multiplies input by three and returns the result." + ... (* x 3))) + + => (help times-three) + Help on function times_three: + + times_three(x) + Multiplies input by three and returns result + (END) + let --- diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 0dbbfd2..4acb72b 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -436,11 +436,17 @@ Finally, of course we need classes! In python we might have a class like:: class FooBar(object): - def __init__(self, x): - self.x = x + """ + Yet Another Example Class + """ + def __init__(self, x): + self.x = x - def get_x(self): - return self.x + def get_x(self): + """ + Return our copy of x + """ + return self.x In Hy: @@ -448,6 +454,7 @@ In Hy: .. code-block:: clj (defclass FooBar [object] + "Yet Another Example Class" [[--init-- (fn [self x] (setv self.x x) @@ -457,6 +464,7 @@ In Hy: [get-x (fn [self] + "Return our copy of x" self.x)]])