Feature: Require @return & Require @since

[aubreypwd]

A new approach from #4 which just focuses on @return and @since and it's requirements from scratch. This needs a lot of testing, but seems to be working well in Sublime and Atom. Please load up some of your recent projects and see if @return is working as you expect.

Closes #8 and #6

This also sets up a basic structure for adding new sniffs.

[aubreypwd]

@JayWood Just putting a request out there to test this in storm and get your blessing.

[aubreypwd]

Just added the Discussion Needed label because I think we need to talk to the FED's about this. They don't really use @since but I (and others) think they should too. Going to wait until FED/BED call to discuss (mostly that it's coming, unless someone vetos it).

[aubreypwd]

	/**
	 * Get single.
	 *
	 * Need to implement in sub-class.
	 *
	 * @since Unknown
	 *
	 * @param array $insert_args Insert arguments.
	 *
	 * @todo docblock needs-documentation
	 */
	abstract function get_single( $insert_args = array() )

Noting that on this, I'm getting a nag to add @return?

[jrfoell]

👍

I approve this change and would actually argue that requiring @return on the abstract docblock is a feature not a bug. In this case since the function can have no body, the documentation is responsible for letting the implementer know what the function should return (array, string, int, mixed, etc.). In the case when it doesn't return anything - we should specify void. I realize this goes against some of our other established @return use cases, but I think it makes sense here.

[aubreypwd]

Yeah, but it will require an @return even if you haven't got a return in the abstracted method (for obvious reasons). It's still an accident. I agree the return should be documented, but if the extended methods don't return anything, that would end up being false.