improving Mojo::Base documentation

[tnishimura]

my diff

Hi, I'd like to help with some of the documentation issues. I'm starting with Mojo::Base (#1119), please see my diff above. The major changes are:

• Expanded SYNOPSIS to be much more detailed and thematic. Might need to be trimmed a bit.
• Organized the importing stuff into to its own section.
• Rewrote the FLUENT INTERFACES section... it uses the code in the synopsis as an example. I left the original in there as FLLUENT INTERFACES (ORIGINAL) if you want to compare. Not sure about this one. Also, added link to wikipedia because I personally had never heard of term "fluent interfaces" before reading this page.
• FUNCTIONS renamed DEFINING ATTRIBUTES AND PROPERTIES, because, well, there's only one function 'has' so we might as well say what 'has' does.
• 'has' section annotated.
• added notes on required attributes to 'has' section
• METHODS section is mostly untouched.

Please tell me what you think, and I'll try to incorporate your throughts before making a PR.

[Grinnz]

Apart from analyzing your suggestions, the issue you linked is specifically about Mojo::DOM. These changes are to Mojo::Base which is unrelated.

[tnishimura]

Whoops, I meant #1119, not #1110. Somehow I got Dom and Base completely confused in my head, even got the title wrong. (I'm also working on the Dom docs)

[kraih]

I'm afraid you might have misunderstood #1119 a bit. We are looking for new documentation, not a reformatting of what's already there. Please be aware that we also care a lot about consistency, so getting rid of the standard attributes section and using completely new code formatting rules are blockers.

[tnishimura]

Ok. I did a bit more than rearrange, but I see your point about consistency.

[kraih]

Here's an example for what kind of PRs i would expect. 8b3e17b

[kraih]

Small, very topic specific sections that elaborate a bit on things new users should know.

[tnishimura]

Gotcha, thanks for letting me know. I don't think I can help then.