State of S26

gistfile1.md

Fellow 6-ers,

I think that the time has come for me to merge the S26 branch into nom. However, before I do so, I would like some feedback on its implications. First of all, here's the diff:

https://github.com/rakudo/rakudo/compare/S26-WHY

And here's a list of known issues:

• Documenting constants and variables is NYI
• Documenting enums and subsets with a trailing declarative doc (#=) requires the trailing comment to follow a semicolon
• Installation of the WHEREFORE for a WHY is done in the WHY read accessor. If multiple objects share a WHY (for example, clones), this could cause some very odd behavior. (I'm thinking this behavior maybe should die, because it's also kind of implemented by the next bullet point)
• Since the WHEREFORE is set via WHY (see previous), the WHEREFORE has to be initialized in advance, because someone can check the WHEREFORE of a Pod block via $=pod. For Routines and Methods, I do this in their clone methods, which could cause strange behaviors if a user clones a method/routine his/herself.
• Right now, two helper methods exist for hooking everything up: set_why and set_docee. If these stay around, I would like for them to become rw methods, but that's beyond my capability at the moment.

Please help me review the code and let me know if you consider anything in the code or in the above list to be a show-stopper. I would like this to get merged earlier so other people can play with the new feature and we can find more sinister bugs before 2014.09 goes out.