[Bf-python] Lets try this

[Stephen Swaney]

Ed Blake wrote:
> 
> first test, I plan to go into every module and update the doc strings.
> [snipped]

This is looks nice.  Very nice.
 
> A question I
> have:  In some modules the doc strings are in the header file, and in others
> it is in the C code.  Which of these is preferred (which should be the
> standard)? 

The doc strings belong in the .c file.

To use formal langauge, the header files ( .h ) contain declarations
and the implementation files ( .c ) contain definitions.  Declarations
announce that something exists and describe the interface to a module,
class, function, whatever.  Definitions allocate storage for
data and functions.

Since a header declares an interface it should only contain the
information that someone needs to use that module.  It can be 
#included in many places so it should not contain data definitions.
The definition must appear only once or the linker gets upset wondering
which piece of code to use.  Doc strings are data so they belong
in the .c file.  Declarations that are only used internally by a
module also belong in the .c file.

So why to we have doc strings in the headers?  It was a historical
artifact that got copied, as these things often do.  In our particular
case, it happens to work.  We recognize it is wrong and have a plan
to change it.

In the meantime, if the doc strings are already in a header, you 
can just edit/update them in place.  If you create new ones, they
belong in the .c files.

> Also should I leave the bit about the operation being in-place
> when the return value is given?

Probably a good idea to leave it in. It is correct and it helps
make things clear.  As I recall, at least one person was slightly 
confused on this issue.

-- 
Stephen Swaney			
sswaney at swbell.net