- Clarified prohibition of signature repetition.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@37 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 9 insertions, 1 deletions

diff --git a/docutils/docs/peps/pep-0257.txt b/docutils/docs/peps/pep-0257.txt
index 48425d9cc..af1239568 100644
--- a/docutils/docs/peps/pep-0257.txt
+++ b/docutils/docs/peps/pep-0257.txt
@@ -113,7 +113,15 @@ Specification
               """function(a, b) -> list"""
 
       This type of docstring is only appropriate for C functions (such
-      as built-ins), where introspection is not possible.
+      as built-ins), where introspection is not possible.  However,
+      the nature of the return value cannot be determined by
+      introspection, so it should be mentioned.  The preferred form
+      for such a docstring would be something like::
+
+          def function(a, b):
+              """Do X and return a list."""
+
+      (Of course "Do X" should be replaced by a useful description!)
 
     Multi-line Docstrings
     ----------------------