[wingide-users] Question/Suggestion: More docstrings

[Tom Stambaugh]

I am *very* happy with the current docstring handling of WingIDE.

I appreciate your reply, your apology is appreciated but not needed :-)

Thanks,
Tom

Wingware Support wrote:
> Tom Stambaugh wrote:
>> I've *always* used "additional docstrings" to elaborate the one-line 
>> docstring associated with each class and method. Perhaps I've 
>> misunderstood the community practices for years, but here's the way I 
>> thought all this worked (and is the way I've written all my code):
>>
>> 1. The docstring is a one-line summary that describes the class or 
>> method. For methods, in particular, it uses an active voice and really 
>> does fit on one (possibly long) line ("""Answers a map associating the 
>> name and versionId of each asset contained in aSubAssemblyBuilder."""")
>>
>> 2. There is, from time to time, a need for additional detail 
>> describing subtle behavior or conditions. This additional detail is 
>> provided by an elaboration of the docstring, at the same indent level. 
>> For example:
>> """This only works when aSubAssemblyBuilder is already cached in the 
>> receiver.
>> - Collects the cached subAssembly corresponding to aSubAssemblyBuilder.
>> - Collects its classNames
>> - For each className, collects its versionId
>> - Forms and answers a map where:
>>     key: className
>>     value: versionId
>> """
> 
> Interesting... I can see this is reasonable as a way to control how much
> the IDE shows.
> 
>> 4. The "docstring" is used as in WingIDE. The additional detail is 
>> used by subsequent developers who may need to understand what the 
>> method is doing and why.
> 
> OK, so sounds like you are happy w/ how it works (not showing second+
> docstring).  If not, please let me know.
> 
> The original poster's request was apparently more about showing 
> docstrings for object attributes, which does seem potentially useful
> and is something we'll keep in mind.
> 
> Sorry for the long delay before replying...
> 
> Thanks,
> 

-- 
Tom Stambaugh, Founder
Zeetix LLC/ZeeGuide/ZeeForge
27 Auburn Street
Brookline, MA 02446
617-734-8934 (land)
617-721-0446 (cell)