MA-946 #time 1h reviewed and updated function docs and other comments

Author: beardyman

RoboFile.php

@@ -14,4 +14,4 @@ public function test () {
 
     	return $res();
 	}
-}
+}

lib/MessageSystems/Transmission.php

@@ -7,8 +7,16 @@
  * @desc SDK interface for managing transmissions
  */
 class Transmission {
+	/**
+	 * @desc singleton holder to create a guzzle http client 
+	 * @var \GuzzleHttp\Client
+	 */
 	private static $request;
 
+	/**
+	 * @desc Mapping for values passed into the send method to the values needed for the Transmission API 
+	 * @var array
+	 */
 	private static $parameterMappings = [
 		'campaign'=>'campaign_id',
 		'metadata'=>'metadata',
@@ -30,6 +38,10 @@ class Transmission {
 		'useDraftTemplate'=>'use_draft_template'
 	];
 
+	/**
+	 * @desc Sets up default structure and default values for the model that is acceptable by the API
+	 * @var array
+	 */
 	private static $structure = [
 		'return_path'=>"default@sparkpostmail.com",
 		'content'=>[
@@ -49,6 +61,10 @@ class Transmission {
 	 */
 	private function __construct() {}
 
+	/**
+	 * @desc Creates and returns a guzzle http client.
+	 * @return \GuzzleHttp\Client
+	 */
 	private static function getHttpClient() {
 		if(!isset(self::$request)) {
 			self::$request = new Client();
@@ -86,8 +102,25 @@ private static function getBaseUrl($config) {
 	 * @desc Method for issuing POST request to the Transmissions API
 	 *
 	 *  This method assumes that all the appropriate fields have
-	 *  been populated by the user through configuration or calling
-	 *  helper methods
+	 *  been populated by the user through configuration.  Acceptable 
+	 *  configuration values are: 
+	 *  'campaign': string, 
+	 *	'metadata': array,
+	 *	'substitutionData': array,
+	 *	'description': string,
+	 *	'replyTo': string,
+	 *	'subject': string,
+	 *	'from': string,
+	 *	'html': string,
+	 *	'text': string,
+	 *	'rfc822Part': string,
+	 *	'headers': array,
+	 *	'recipients': array,
+	 *	'recipientList': string,
+	 *	'template': string,
+	 *	'openTracking': boolean,
+	 *	'clickTracking': boolean,
+	 *	'useDraftTemplate': boolean 
 	 *
 	 * @return array API repsonse represented as key-value pairs
 	 */

test/unit/SparkPostTest.php

@@ -7,6 +7,7 @@ class SparkPostTest extends \PHPUnit_Framework_TestCase {
 
 	/**
 	 * @desc Ensures that the configuration class is not instantiable.
+	 * @covers SparkPost::__construct
 	 */
 	public function testConstructorCannotBeCalled() {
 		$class = new \ReflectionClass('\MessageSystems\SparkPost');
@@ -16,6 +17,7 @@ public function testConstructorCannotBeCalled() {
 	/**
 	 * @desc Tests that an exception is thrown when a library tries to recieve the config and it has not yet been set.
 	 * 		Since its a singleton this test must come before any setConfig tests.
+	 * @covers SparkPost::getConfig
 	 * @expectedException Exception
 	 * @expectedExceptionMessage No configuration has been provided
 	 */
@@ -25,6 +27,7 @@ public function testGetConfigEmptyException() {
 
 	/**
 	 * @desc Tests that the api key is set when setting the config
+	 * @covers SparkPost::setConfig
 	 * @expectedException Exception
 	 * @expectedExceptionMessage You must provide an API key
 	 */
@@ -34,6 +37,7 @@ public function testSetConfigAPIKeyNotSetException() {
 
 	/**
 	 * @desc Tests that the api key is set when setting the config and that its not empty
+	 * @covers SparkPost::setConfig
 	 * @expectedException Exception
 	 * @expectedExceptionMessage You must provide an API key
 	 */
@@ -43,6 +47,7 @@ public function testSetConfigAPIKeyEmptyException() {
 
 	/**
 	 * @desc Tests overridable values are set while invalid values are ignored
+	 * @covers SparkPost::setConfig
 	 */
 	public function testSetConfigMultipleValuesAndGetConfig() {
 		SparkPost::setConfig(['key'=>'lala', 'version'=>'v8', 'port'=>1024, 'someOtherValue'=>'fakeValue']);

test/unit/TransmissionTest.php

@@ -8,14 +8,18 @@
 use GuzzleHttp\Stream\Stream;
 
 
-/**
- * 
- *
- */
 class TransmissionTest extends \PHPUnit_Framework_TestCase {
 
 	private $client = null;
 
+	/**
+	 * Allows access to private methods in the Transmission class
+	 * 
+	 * This is needed to mock the GuzzleHttp\Client responses
+	 * 
+	 * @param string $name
+	 * @return ReflectionMethod
+	 */
 	private static function getMethod($name) {
 		$class = new \ReflectionClass('\MessageSystems\Transmission');
 		$method = $class->getMethod($name);
@@ -35,14 +39,16 @@ public function setUp() {
 
 	/**
 	 * @desc Ensures that the configuration class is not instantiable.
+	 * @covers Transmission::__construct
 	 */
 	public function testConstructorCannotBeCalled() {
 		$class = new \ReflectionClass('\MessageSystems\Transmission');
 		$this->assertFalse($class->isInstantiable());
 	}
 
 	/**
-	 * 
+	 * @desc tests happy path
+	 * @covers Transmission::all
 	 */
 	public function testAllWithGoodResponse() {
 		$mock = new Mock([new Response(200, [], Stream::factory('{"results":[{"test":"This is a test"}, {"test":"two"}]}'))]);
@@ -52,7 +58,8 @@ public function testAllWithGoodResponse() {
 	}
 
 	/**
-	 * 
+	 * @desc tests happy path
+	 * @covers Transmission::find
 	 */
 	public function testFindWithGoodResponse() {
 		$mock = new Mock([new Response(200, [], Stream::factory('{"results":[{"test":"This is a test"}]}'))]);
@@ -62,7 +69,8 @@ public function testFindWithGoodResponse() {
 	}
 
 	/**
-	 *
+	 * @desc tests 404 bad response
+	 * @covers Transmission::find
 	 */
 	public function testFindWith404Response() {
 		$mock = new Mock([new Response(404, [])]);
@@ -77,7 +85,8 @@ public function testFindWith404Response() {
 	}
 
 	/**
-	 *
+	 * @desc tests unknown bad response
+	 * @covers Transmission::find
 	 */
 	public function testFindWithOtherBadResponse() {
 		$mock = new Mock([new Response(400, [])]);
@@ -92,7 +101,8 @@ public function testFindWithOtherBadResponse() {
 	}
 
 	/**
-	 * 
+	 * @desc tests happy path
+	 * @covers Transmission::send
 	 */
 	public function testSuccessfulSend() {
 		$body = ["result"=>["transmission_id"=> "11668787484950529"], "status"=>["message"=> "ok","code"=> "1000"]];
@@ -103,7 +113,8 @@ public function testSuccessfulSend() {
 	}
 
 	/**
-	 * 
+	 * @desc tests bad response
+	 * @covers Transmission::send
 	 */
 	public function testSendForRequestException() {
 		$body = ['errors'=>['This is a fake error']];