You've made a very interesting point on how difficult it is to write proper documentation. I hope that Todd will reflect on that.
Le mar. 10 déc. 2019 à 23:45, Rocco Caputo <rcap...@pobox.com> a écrit : > On Dec 10, 2019, at 15:35, ToddAndMargo via perl6-users < > perl6-us...@perl.org> wrote: > > A method is a routine that you feed: Str.foo. > > > It seems that you're saying the difference between a method and other > kinds of routines is that methods are "fed" something? > > The only thing I can think of that routines are fed are parameters. So it > seems that you're saying methods must have parameters, and conversely, > routines without parameters must not be methods. > > But that method invocation doesn't have parameters. By your definition, > foo is not a method. > > I know what routines and methods are, and I know what feeding is in the > transitive sense, and what you just wrote doesn't seem to describe a method > call (or its difference from other function calls). > > You seem to be describing technical things with metaphor. Precision is > important. Without it you run a significant risk of being misunderstood > unless the reader shares your particular frame of reference. > > Think of "contains" as looking for a Needle in a Haystack. > You feed contains data and what you are lookig for. In > return is tells you True or False > > say "abc".contains( "a" ); > True > > > So you want "feed" to mean both passing parameters and supplying an > invocant? > > You could just have said so. Something like "A method is a routine called > on an object." I can see why you'd want to use metaphor to spice that up. > It's silly, if not tedious, if not completely pointless to restate common > OO knowledge everywhere you intend to use OO. > > Case insensitive contains: > Note: "fc" converts you to lower case. It also converts weird charters > to > something on your keyboard > > > I can't use this as documentation. "something on [my] keyboard" is too > imprecise (what language is my keyboard?). I'll need to consult the > technical documentation to understand "fc" well enough to actually use it. > Even worse, I suspect "fc" is some kind of mnemonic, and I'd probably have > understood it better if the expanded term was mentioned. > > It seems like using and documenting "fc" adds extraneous details and > distracts from what this article intends to discuss. Splitting it into two > articles with better focus in each would probably be an improvement. > > "Str" > is the string data (Haystack) that will be operated on by the method > (contains) > > > "data" is wasted everywhere you've used it. You should consider removing > it. > > ""is the string that will be searched by the 'contains' method" is better > without "data" and possibly without "(Haystack)". > > Your personal note is probably fine since you know what you meant when you > wrote it. As documentation for a general audience, I'd say it's badly > written and needs significant edits. You should totally self-publish it > anyway. Probably in a public repository so that interested people will > help you improve it. > > -- > Rocco Caputo <rcap...@pobox.com> >
