On Fri, Apr 23, 2010 at 19:49, Daniel Convissor <dani...@analysisandsolutions.com> wrote: > Hi Hannes: > > On Fri, Apr 23, 2010 at 05:31:28PM +0200, Hannes Magnusson wrote: >> On Fri, Apr 23, 2010 at 14:15, Daniel Convissor >> > >> > Several of the DateTime examples are overblown in general. ?The one >> > DateTime::add() <example> has six sample statements in it. ?For such a >> > simple function, only one example is necessary. >> >> I like multiple examples, especially when combined with a complicated >> bastard as DateInterval. > > Yeah. Things that have strange/complicated behaviors need multiple > demonstrations. But simple things should have one, straight-ahead > example.
The idea behind DateTime->add() is simple, but the usage isn't. Most function have accept bunch of "weird arguments". Take substr() as an example, which is drop dead *basic* function, can sometimes make your hair raise when you throw in negative negative $start and/or negative $length. There is no doubt that more examples, no matter how trivial they may seem, are better then "concatenated" example. When an example however becomes "to large" we should consider splitting them into multiple examples, with <screen>s. So in the DateTime->add() case, if you feel it is to big; consider chunking it into "basic usage", months, and years+months+days, ..., or something along those lines. -Hanes
