[wingide-users] Question/Suggestion: More docstrings
tms at zeetix.com
Mon Mar 15 13:03:58 MDT 2010
I am *very* happy with the current docstring handling of WingIDE.
I appreciate your reply, your apology is appreciated but not needed :-)
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
>> - 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...
Tom Stambaugh, Founder
27 Auburn Street
Brookline, MA 02446
More information about the wingide-users