documentation!

[Bystroushaak]

Dne 22.7.2016 v 06:43 'Jason Grossman' spam-me at xeny.net [self-interest] 
napsal(a):
> IMO the worst thing that ever happened to object-oriented programming
> was the idea that if we write good code our environments will
> automatically be self-documenting.

I am kind of fighting with this now, when I am trying to write first 
projects in Self and almost no method in collections is documented. 
Sometimes it may be clear from the name, but even then it is kinda hard 
to deduce what types the method accepts as parameters (strings 
especially, where there is methods that accepts just one character long 
strings).

I think that documentation in method comments would be great for the web 
browsers like http://browser.russell.larrikin.org.

On the slightly different topic: I implemented the splitBy:* method, 
which allows you to split source strings by variable length strings. 
Something like python's str.split(str). Either I wasn't able to find it, 
or it wasn't there. Would it be possible (or desirable) to add it to 
official Self distribution (if it isn't already there)? I use it all the 
time for simple text parsing like

	protocol: ('http://domain' splitBy: '://') first

Another issue - the unittests. I've managed to find assert:, and assert: 
Equals:, but they are hidden somewhere deep in the test suite for traits 
oddball and there is also assert: in traits block and I am confused on 
what should I use.

*
bootstrap addSlotsTo: bootstrap stub -> 'traits' -> 'string' -> () From: 
( | {
          'Category: transforming\x7fCategory: tokenizing\x7fComment: 
Split the string by the `word`. If the word is empty,
return string splitted by charactes. If it is nil,
return list with the whole string.\x7fModuleInfo: Module: http_client 
InitialContents: FollowSlot'

          splitBy: word = ( |
              current <- 0.
              full_size.
              out.
             |
             out: list copy.
             word = nil ifTrue: [^out add: self].

             full_size: self size.
             full_size <= word size ifTrue: [^out].
             word size = 0 ifTrue: [^self asList.].

             [current <= full_size] whileTrue: [
               self
                 findSubstring: word
                 StartingAt: current
                 IfPresent: [| :pos. |
                   out add: (self copyFrom: current UpTo: pos).
                   current: pos + (word size).
                 ]
                 IfAbsent: [
                   (current = 0) ifTrue: [^ (list copy) add: self.].

                   out add: (self copyFrom: current UpTo: full_size).
                   ^out.
                 ].
             ].
             ^out).
         } | )