"Richard A. O'Keefe" wrote:
> 
> Doug Way <dway at riskmetrics.com> wrote:
>         It hadn't even occured to me that either method would accept a
>         collection of strings.  In my defense, the comment for
>         findBetweenSubStrs:  is very unclear about what exactly is expected as a
>         parameter.
> 
> The method comment says
> 
>     findBetweenSubStrs: delimiters
>        "Answer the collection of tokens that result from parsing self.
>         Tokens are separated by substrings,
>         as listed in the Array delimiters."
> 
> It looks very much as though it wants an Array of strings, no?
> That certainly won't mislead, because an Array of strings works.
> There's a bunch of methods in Squeak's String class that take the
> same kind of parameter.

Alright, in retrospect it's not really misleading, but it still wasn't clear enough to make it obvious what it was expecting at first glance.  (At least I didn't figure it out the first time. :) )  Part of the problem is that it does accept a single string as an argument, which threw me off.  Somehow I assumed the "SubStrs" in the method name referred to the returned substrings, not the delimiters. (kind of like the asArrayOfSubstrings VSE method that Chris was talking about)

I still think my comment clarification would help. (okay, maybe it should say it expects a "collection of Strings and/or Characters".)

> Look in
> 
>     skipAnySubStr: delimiters startingAt: start
>        "Answer the index of the last character within the receiver,
>         starting at start, that does NOT match one of the delimiters.
>         delimiters is a (sic!) Array of substrings (Characters also
>         allowed).  If the receiver is all delimiters, answer size + 1."
> 
> In fact *this* comment is not unclear, it's wrong.  It doesn't answer
> the index of the *last* non-delimiter character, it answers the index
> of the *first* such character.

True.  Travis had a good point here... comments that are too detailed and start to look like code (e.g. "answer size + 1") are redundant and more likely to become incorrect as time passes, and are often worse than no comments at all.  Keep comments simple and high-level, and only when really needed.

> It looks as though the method comments for all these methods could do with
> overhauling.

Yes.

- Doug Way
  dway at riskmetrics.com