Remove excess `@since` about subtitles

[philiparthurmoore]

I'll give the @since a look. In general I use them when developing in the future will be easier for me. Rather than look through old commit logs, it's easier to read when something happened inline.

As a sidenote, I think there's way too much inline documentation.

I've addressed this in the code. :)

 * A note to plugin developers and theme makers: you may be wondering why I've taken
 * the time to document code that to seasoned vets seems obvious, for example explaining
 * that functions inside of classes are called methods. The reason I've done this is primarily
 * because there was a time when looking at the following code would have made absolutely no
 * sense to me. At that time, I would have loved for there to have been robust inline documentation
 * explaining to me what was happening. Consider the following documentation a gift to newbies and
 * also a gift to my future self, who will undoubtedly look back on some of what I've written here
 * with confusion and chagrin.

That documentation is for me more than anyone else. Happy to take the "more documentation because I'm selfish and need reminders of why I did something" route over the "way too much information" route.

[rmccue]

That documentation is for me more than anyone else. Happy to take the "more documentation because I'm selfish and need reminders of why I did something" route over the "way too much information" route.

The existing documentation actually makes this unusable for me, as I can't tell what's happening in the code - it's hard at times to even find what code's executing. For example:

/**
 * Put together the final title and subtitle set
 *
 * @since 1.0.0
 */
$title = $title . ' ' . $subtitle;

It's immediately obvious to those reading the code that you're combining title and subtitle with a space, the documentation here is completely superfluous.

I'm not against inline documentation, but there's certainly the ability to go overboard here.

Rather than look through old commit logs, it's easier to read when something happened inline.

That's exactly what git blame (and svn blame, etc) is designed for, and it gives you a much richer history.

[philiparthurmoore]

This is as much for beginners as it is for advanced developers, like you. I totally get what you're saying but I doubt I'll remove those notes. They're more helpful to me than they are harmful.

[rmccue]

FWIW, here's what the main class looks like stripped down to 391 lines. IMO, it still has liberal amounts of documentation, but is much more readable.

I understand if you don't want to remove the documentation, but keep in mind that inline docs are much like whitespace in designs: the right amount is great, but too much will make it unreadable.

[philiparthurmoore]

Cheers.