On Fri, Sep 14, 2018 at 6:19 AM Todd Chester <toddandma...@zoho.com> wrote: > > > > On 09/14/2018 03:34 AM, Simon Proctor wrote: > > I think the docs of objects (sorry on my phone no link) describe object > > creation and the default new quite well. > > They most probably are and most developers would have no issues > figuring them out. > > If a common user can't make heads or tails out of them, then > they need some work. Perl 5's perldocs are wonderfully easy > to understand. The developers have their own specifications. > The Docs need to be understandable by the riff raff. > > > Do a search for objects. > > What do you mean? > > Can you throw an example at me?
In the Perl 6 docs you often are looking for a subroutine or a method indiscriminately. So the routine pages pull from both lists dynamically. That is what happened here. In the case of `.new()` this is a really bad idea. That is because every object has a new. Since the pages for routines pull the method documentation out of its broader context, it can sometimes be confusing. The broader context being the pages for the types themselves. This works decently for things like `.substr()` because there is really only one type which that works on, and is fairly easy to guess about the wider context. In the case of `.new()` there is no way to guess about the wider context. It is also one of the methods that most people would just get, so the documentation for each instance of this method only describes the differences from the norm. Basically the documentation for `.new()` needs to be hand-crafted.
