docstrings style question

[Steve Brown]

"Russ P." <Russ.Paielli at gmail.com> wrote in message 
news:d2a08eac-3ae7-4710-9b49-cdbe365a25ef at d21g2000prf.googlegroups.com...
> On Jan 9, 11:51 pm, Fredrik Lundh <fred... at pythonware.com> wrote:
>> Steve Brown wrote:
>> > I've got a series of modules which look like this:
>>
>> > #************
>> > #
>> > # Temperature Sense Test
>> > #
>> > #************
>> > class Test3(ar_test.AR_TEST):
>> >     """Temperature Sense Test"""
>>
>> > I don't like the duplicated information: But the comment is attractive, 
>> > and
>> > the docstring self.__doc__ is already in use in the test log. I've read 
>> > that
>> > all modules and classes should have docstrings, but I don't really have
>> > anything else to say, and each module contains only one class. I don't 
>> > think
>> > that
>>
>> > """Temperature Sense Test"""
>> > class Test3(ar_test.AR_TEST):
>> >     """Temperature Sense Test"""
>>
>> > would be a real improvement.
>>
>> > What do you think?
>>
>> since you already seem to cater to your audience (clearly marked
>> comments for people browsing the code, brief docstrings for the test
>> log), I don't really see why you should change anything.
>>
>>  > I've read that all modules and classes should have docstrings
>>
>> if nobody's going to read them, there's no reason to add them.  don't
>> treat generic style advice as dogma.
>>
>> </F>
>
> Well, trivial modules certainly don't need much documentation, but he
> didn't say they were trivial. I assumed there was more to them then he
> showed.

All of the complexity is in the test framework. I've been working on paring 
back the tests to make them simple to understand, create and modify, which 
is how I've come to this: I'm still trying to remove lines. The test itself 
is a now a linear script of 20-40 lines, and I'm still working on them.

However, it is relatively important to make the documentation right for 
these simple scripts.

The docstring/comment does need to show some embedded dependancies, I just 
chose one without any.

I realise from reading Jeroen Ruigrok van der Werven's comment that I should 
probably also
care what epydoc makes of my doc strings, -- that's an additional 
constraint.