gfldex++ for blogging. My basic feeling about documentation is that it should:
1. Explain the construct, it's purpose and behaviour. 2. Give code examples that explain one thing and do it well. The original example was there to explain that you would not get DEFAULT exports if you pass a positional in. After it was changed it no longer compiled, and no longer was clear to me what it was showing. Though, I agree with you that type captures in EXPORT are worth showing, and since we don't have a cookbook thing yet, I put them into a second example which aims to show them in the most minimal way possible. https://github.com/perl6/doc/commit/5dbb3a18f79bd4e45e245c049ada56e9abfa8b7f Feel free to make changes as always. And thanks for your contributions! I suppose we should leave this ticket for the bug now ;) On Thu, Jan 21, 2016 at 12:59 AM Wenzel P. P. Peppmeyer < wenzel.peppme...@gmx.de> wrote: > > > On Mon, 18 Jan 2016, Lloyd Fournier via RT wrote: > > > gfldex, I see you've edited the second EXPORT example, but to me it's > made > > it much less clear what's going on. > > I'm not happy with that example myself and intend to change it. > > > I see where you are going, trying to show that the power of ::T type > > captures can still be used in EXPORT, but I think we should leave that > > up to the imagination of the user. > > I do not agree with the notion "Let's not tell them!". The whole point of > a documentation is to save the person who reads it time. This is one bug > report out of 5 related to EXPORT and/or type captures. It took me about 6 > hours to find all the bits that work/don't work and led to the following > blog post [1]. Let's assume that in the course of the next year alone 100 > brave souls (likely a low figure) read that section of the doc. That's 600 > manhours that could be spend more productive. The whole point of Perl 6 is > to let programmers be more lazy. Productive! Productive I mean! > > [1] https://gfldex.wordpress.com/ >
