[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: docstrings and elisp reference

From: Richard Stallman
Subject: Re: docstrings and elisp reference
Date: Tue, 06 Jun 2017 18:42:11 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > I was thinking (naively?) that having the docstrings on one side
  > and the reference on the other side was not a very efficient way
  > to maintain documentation. Is everything in the documentation
  > actually written by hand based on the docstrings? Wouldn't it be
  > nicer to have good docstrings and use them directly in the
  > documentation to avoid duplication of work?

Absolutely not!  That's a recipe for a bad manual.  The text of a good
manual section is totally different from a series of doc strings.

Doc strings are read one by one.  Each one describes one function or
variable in isolation.  They are written specifically for this kind of

By contrast, a section in a manual describes several related functions
and variables, and it should be written in an integrated way that
flows smoothly.  Meanwhile, common material should be stated only

Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]