Updating documentation on scaffold api

quantum/gate/scaffold/ScaffCCAPI.hpp

+/***********************************************************************************
+ * Copyright (c) 2016, UT-Battelle
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *   * Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *   * Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *   * Neither the name of the xacc nor the
+ *     names of its contributors may be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * Contributors:
+ *   Initial API and implementation - Alex McCaskey
+ *
+ **********************************************************************************/
 #ifndef QUANTUM_GATE_SCAFFOLD_SCAFFCCAPI_HPP_
 #define QUANTUM_GATE_SCAFFOLD_SCAFFCCAPI_HPP_
 
@@ -10,29 +40,52 @@ using namespace qci::common;
 
 namespace scaffold {
 
+/**
+ * The ScaffCCAPI is a simple utility class that provides
+ * methods for interacting with an installed Scaffold compiler.
+ * It's main function is to take user-specified XACC kernel
+ * source code and compile it to flatted QASM using the
+ * Scaffold compiler.
+ */
 class ScaffCCAPI {
 
 public:
 
+	/**
+	 * Return a string containing flatted QASM representing
+	 * the provided high level Scaffold source code. This method
+	 * assumes that the Scaffold compiler is on the current user's
+	 * PATH and is called scaffcc.
+	 *
+	 * @param source The scaffold kernel source code.
+	 * @return flattenedQASM The QASM representation of the given source.
+	 */
 	std::string getFlatQASMFromSource(const std::string& source) {
 
 		// Check if scaffcc exists on the PATH
 		if (std::system("which scaffcc > /dev/null 2>&1") == 0) {
 
+			// Create a temporary scaffold soruce file
 			std::ofstream tempSrcFile(".tmpSrcFile.scaffold");
 			tempSrcFile << source;
 			tempSrcFile.close();
 
+			// Execute the scaffold compiler
 			std::system("scaffcc -fp .tmpSrcFile.scaffold");
+
+			// Remove the temporary source file, we don't need it anymroe
 			std::remove(".tmpSrcFile.scaffold");
 
+			// Read in the generated QASM
 			std::ifstream flatQASM(".tmpSrcFile.qasmf");
 			std::string qasm((std::istreambuf_iterator<char>(flatQASM)),
 					std::istreambuf_iterator<char>());
 
+			// Remove created scaffold files.
 			std::remove(".tmpSrcFile.qasmf");
 			std::remove(".tmpSrcFile.qasmh");
 
+			// Return the QASM
 			return qasm;
 		} else {
 			QCIError(

quantum/gate/scaffold/ScaffoldCompiler.cpp

@@ -32,10 +32,17 @@ void ScaffoldCompiler::modifySource() {
 
 std::shared_ptr<IR> ScaffoldCompiler::compile() {
 
+	// Create an instance of our ScaffCC API
+	// so that we can interact with a locally installed
+	// scaffcc executable
 	scaffold::ScaffCCAPI scaffcc;
 
+	// Compile the source code and return the QASM form
+	// This will throw if it fails.
 	auto qasm = scaffcc.getFlatQASMFromSource(kernelSource);
 
+	// Generate a GraphIR instance, ie a graph
+	// tensor references making up this QASM
 	std::cout << "Flat QASM: \n" << qasm << "\n";
 	return std::make_shared<GraphIR>();
 }

quantum/gate/scaffold/ScaffoldCompiler.hpp

@@ -44,25 +44,31 @@ namespace xacc {
 namespace quantum {
 
 /**
- *
+ * The Scaffold compiler is a subclass of the XACC
+ * Compiler that implements the compile() and modifySource() methods
+ * to handle generation of quantum assembly language (or QASM)
+ * using an installed Scaffold compiler.
  */
 class ScaffoldCompiler : public Compiler<ScaffoldCompiler> {
 
 public:
 
 	/**
-	 *
-	 * @return
+	 * Execute the Scaffold compiler to generate an
+	 * XACC intermediate representation instance.
+	 * @return ir XACC intermediate representation
 	 */
 	virtual std::shared_ptr<IR> compile();
 
 	/**
-	 *
+	 * This method is intended to modify the incoming
+	 * source code to be compiled to be amenable to the
+	 * Scaffold compiler.
 	 */
 	virtual void modifySource();
 
 	/**
-	 *
+	 * The destructor
 	 */
 	virtual ~ScaffoldCompiler() {}