Subject: | Document lazy_build as discouraged more prominently |
As of Moose 2, 'lazy_build' disappeared from places it was documented,
including Moose::Manual::Attributes and Moose::Manual::BestPractices, but this
was not documented in a "DOCUMENTATION" section of Changes.
In Moose 2.0602, "avoid lazy_build" was added to Moose::Manual::BestPractices.
This was also not in a "DOCUMENTATION" section of Changes.
Nor were these changes mentioned in Moose::Manual::Delta.
This is confusing for anyone who remembers reading about 'lazy_build' in an old
version of Moose and now can't find it where it used to be.
I suggest documenting 'lazy_build' as 'discouraged' more obviously in at least
the following places:
* Moose::Manual::Delta -- in the 2.0 section
* Moose::Meta::Attribute -- in the 'lazy_build' section
* Changes -- noting the changes above in the DOCUMENTATION section
I think it would be useful to note in Moose::Manual::Attributes that 'lazy_build'
used to be encouraged as a best practice and is now discouraged.
This will make it easier for people looking for it (a) to find it, and (b)
find out it is discouraged.