"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.  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.  For example,
>         'abc' skipAnySubStr: {','} startingAt: 1
> answers 1, not 3.  Both comments are misleading.  Any collection (such
> as an OrderedCollection) will do just fine.
>
>         #findBetweenSubStrs:  expects either a collection of Characters,
>         or a collection of Strings.  It does barf if you pass it a single
>         Character, which is probably good.
>
> In fact it expects a collection of (Characters or Strings); some elements
> might be Characters and other elements might be Strings.
>
> It looks as though the method comments for all these methods could do with
> overhauling.

Yeah. Like, remove them. Method comments are more often wrong than right, use them
sparingly.

--
Travis Griggs (a.k.a. Lord of the Fries)
Member, Fravenic Skreiggser Software Collective
Key Technology
"In times of change, learners inherit the world, while the learned find they have
inherited a world that no longer exists"-- L. Tom Perry