New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cleanup some documentation to make it more newbie friendly #13

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
2 participants
@bubaflub

bubaflub commented Jan 11, 2015

I am partaking in NEILB's CPAN monthly pull request challenge and I was given the Moo module. I emailed briefly with HAARG about contributing some small edits to the main documentation to make it a little more newbie friendly.

These are the edits that I think clarify a bit of the how, what, and why of Moo. As a total Moo newbie I am simultaneously extremely qualified and extremely unqualified to write these docs, so any feedback is appreciated.

Also, a few questions:

  • A number of places in the POD the word "Moo" is a link (i.e. L) and in some other places it is in a fixed-width font (i.e. C). Should we choose just one or the other?
  • A few of the main function descriptions weren't clear to me:
    • Some of the text on the "is => lazy" attribute is a bit complicated.
    • handles takes a string, arrayref, and a hashref but it doesn't specify how those are different
    • it took me a while to understand the predicate attribute but I'm not really sure of a better way to write it
  • Is there a better ordering of the functions in the POD?
  • Should we include a more in-depth description of the problems with circular references and weak references? Is this a common problem that people using M* will face?

Thanks!

Bob

@haarg

This comment has been minimized.

Show comment
Hide comment
@haarg

haarg Jan 16, 2015

Member

I like the changes so far, aside from a couple nits. As for the questions:

  • It would probably be good to normalize the formatting of Moo. It's pretty pointless for the pod to link to itself, so I'd say it should usually just be plain text. C<> would be appropriate if it was referring to the actual text you include in your files.
  • is => 'lazy' is the same as is => 'ro', lazy => 1, builder => 1, or is => 'ro', lazy => 1 if a default or builder is provided.
  • handles => [ 'method' ] means $object->method is the same as $object->attribute->method
  • handles => { alias => 'method' } means $object->alias is the same as $object->attribute->method
  • handles => 'RoleName' means $object->method is the same as $object->attribute->method, but for every method provided by the given role. The object stored in the attribute is not required to actually consume the given role.
  • A predicate returns true if the attribute has a set value. Values can be set explicitly in the constructor or by using an rw accessor. They can also be set by default values, either in the constructor for non-lazy attributes or by calling the accessor for lazy attributes.
  • The current function ordering seems OK to me, but I'm probably not the best judge of that.
  • I'm not sure if Moo's docs are the best place to elaborate on weak references, but it seems like there should be somewhere we can link that would provide more details. Linking to weaken in Scalar::Util would be a start.
Member

haarg commented Jan 16, 2015

I like the changes so far, aside from a couple nits. As for the questions:

  • It would probably be good to normalize the formatting of Moo. It's pretty pointless for the pod to link to itself, so I'd say it should usually just be plain text. C<> would be appropriate if it was referring to the actual text you include in your files.
  • is => 'lazy' is the same as is => 'ro', lazy => 1, builder => 1, or is => 'ro', lazy => 1 if a default or builder is provided.
  • handles => [ 'method' ] means $object->method is the same as $object->attribute->method
  • handles => { alias => 'method' } means $object->alias is the same as $object->attribute->method
  • handles => 'RoleName' means $object->method is the same as $object->attribute->method, but for every method provided by the given role. The object stored in the attribute is not required to actually consume the given role.
  • A predicate returns true if the attribute has a set value. Values can be set explicitly in the constructor or by using an rw accessor. They can also be set by default values, either in the constructor for non-lazy attributes or by calling the accessor for lazy attributes.
  • The current function ordering seems OK to me, but I'm probably not the best judge of that.
  • I'm not sure if Moo's docs are the best place to elaborate on weak references, but it seems like there should be somewhere we can link that would provide more details. Linking to weaken in Scalar::Util would be a start.
@haarg

This comment has been minimized.

Show comment
Hide comment
@haarg

haarg Feb 1, 2015

Member

Merged as 055e4b2, with some minor tweaks.

Member

haarg commented Feb 1, 2015

Merged as 055e4b2, with some minor tweaks.

@haarg haarg closed this Feb 1, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment