Merge pull request #17 from apiaryio/develop

apiaryio · Jul 10, 2013 · acf2414 · acf2414
2 parents df9a17f + c13aeff
commit acf2414
Show file tree

Hide file tree

Showing 17 changed files with 497 additions and 140 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -5,9 +5,6 @@ compiler:
 script: ./configure && make test
 before_install:
   - git submodule update --init --recursive
-branches:
-  only:
-    - master
 notifications:
   email:
     recipients:

diff --git a/configure b/configure
@@ -26,6 +26,11 @@ parser.add_option("--debug",
     dest="debug",
     help="Also build debug build")
 
+parser.add_option("--dest-cpu",
+    action="store",
+    dest="dest_cpu",
+    help="CPU architecture to build for. Valid values are: ia32, x64")
+
 (options, args) = parser.parse_args()
 
 def write(filename, data):

diff --git a/src/Blueprint.h b/src/Blueprint.h
@@ -13,171 +13,204 @@
 #include <string>
 #include <utility>
 
+/**
+ *  API Blueprint Abstract Syntaxt Tree
+ *  -----------------------------------
+ *
+ *  Data types in this documents define the API Blueprint AST.
+ */
+
 namespace snowcrash {
 
-    //
-    // Generic types
-    //
-
-    // Name of section / element. Plain text
+    /** Name of a an API Blueprint entity. */
     typedef std::string Name;
 
-    // Section Description. Rendered HTML from Markdown
+    /** 
+     *  \brief An API Blueprint entity Description.
+     *
+     *  Depending on parser setting the description might be 
+     *  rendered HTML from Markdown or raw Markdown.
+     */
     typedef std::string Description;
 
-    // URI
+    /** URI */
     typedef std::string URI;
 
-    // URI template
+    /** URI template */
     typedef std::string URITemplate;
 
-    // HTTP Method
+    /** HTTP Method */
     typedef std::string HTTPMethod;
 
-    // Key:Value pair
+    /** A generic key - value pair */
     typedef std::pair<std::string, std::string> KeyValuePair;
 
-    // Default Container for collections
-    // FIXME: C++11 template aliases
+    /**
+     * Default Container for collections.
+     *
+     *  FIXME: Use C++11 template aliases when migrating to C++11.
+     */
     template<typename T>
     struct Collection {
         typedef std::vector<T> type;
         typedef typename std::vector<T>::iterator iterator;
         typedef typename std::vector<T>::const_iterator const_iterator;
     };
 
-    //
-    // API Blueprint sections
-    //
-
-    // Asset data
+    /** An asset data */
     typedef std::string Asset;
 
-    // Metadata key-value pair, e.g. "HOST: http://acme.com"
+    /** 
+     *  \brief Metadata key-value pair,
+     *
+     *  E.g. "HOST: http://acme.com"
+     */
     typedef KeyValuePair Metadata;
 
-    // Header key-value pair, e.g. "Content-Type: application/json"
+    /** 
+     *  \brief  Header key-value pair.
+     *
+     *  E.g. "Content-Type: application/json"
+     */
     typedef KeyValuePair Header;
 
-    // Parameter
+    /** Parameter */
     struct Parameter {
 
-        // Parameter Name
+        /** Parameter Name */
         Name name;
 
-        // Parameter Description
+        /** Parameter Description */
         Description description;
 
         // TODO: type, optional, default value
     };
 
-    // Payload
+    /**
+     *  Payload
+     */
     struct Payload {
 
-        // Payload Name
+        /** A Payload Name */
         Name name;
 
-        // Payload Description
+        /** Payload Description */
         Description description;
 
-        // Parameters
+        /** Payload-specific Parameters */
         Collection<Parameter>::type parameters;
 
-        // Headers
+        /** Payload-specific Headers */
         Collection<Header>::type headers;
 
-        // Body
+        /** Body */
         Asset body;
 
-        // Schema
+        /** Schema */
         Asset schema;
     };
 
-    // Resource Object
+    /** Resource Object */
     typedef Payload ResourceObject;
 
-    // Request
+    /** Request */
     typedef Payload Request;
 
-    // Response, a payload where name is HTTP status code
+    /** 
+     *  \brief Response
+     *
+     *  A payload returned in a response to an action.
+     *  Payload's name represents the HTTP status code.
+     */
     typedef Payload Response;
 
-    // Method
+    /**
+     *  Method
+     */
     struct Method {
 
-        // HTTP method
+        /** HTTP method */
         HTTPMethod method;
 
-        // Method name
+        /** A Method name */
         Name name;
 
-        // Description
+        /** Description */
         Description description;
 
-        // Parameters
+        /** Method-specfic Parameters */
         Collection<Parameter>::type parameters;
 
-        // Headers
+        /** Method-specific HTTP headers */
         Collection<Header>::type headers;
 
-        // Requests
+        /** Requests */
         Collection<Request>::type requests;
 
-        // Responses
+        /** Responses */
         Collection<Response>::type responses;
     };
 
-    // Resource
+    /**
+     *  API Resource
+     */
     struct Resource {
 
-        // URI template
+        /** URI template */
         URITemplate uriTemplate;
 
-        // Resource Name
+        /** A Resource Name */
         Name name;
 
-        // Description
+        /** Description of the resource */
         Description description;
 
-        // Object represented by this resource
+        /** Object model representing this Resource */
         ResourceObject object;
 
-        // Parameters
+        /** Parameters */
         Collection<Parameter>::type parameters;
 
-        // Headers
+        /** Resource-specific HTTP Headers */
         Collection<Header>::type headers;
 
-        // Methods
+        /** A set of HTTP Methods specified for this Resource */
         Collection<Method>::type methods;
     };
 
-    // Group of resources
+    /**
+     *  Group of API Resources
+     */
     struct ResourceGroup {
 
-        // Group Name
+        /** A Group Name */
         Name name;
 
-        // Group Description
+        /** Group description */
         Description description;
 
-        // Resources
+        /** Resources */
         Collection<Resource>::type resources;
     };
 
-    // API Blueprint
+    /** 
+     *  \brief API Blueprint AST
+     *
+     *  This is top-level (or root if you prefer) of API Blueprint abstract syntax tree.
+     *  Start reading a parsed API here.
+     */
     struct Blueprint {
 
-        // Metadata
+        /** Metadata */
         Collection<Metadata>::type metadata;
 
-        // API Name
+        /** The API Name */
         Name name;
 
-        // API Overview
+        /** An API Overview description */
         Description description;
 
-        // Resource Groups
+        /** The set of API Resource Groups */
         Collection<ResourceGroup>::type resourceGroups;
     };
 }

diff --git a/src/BlueprintParserCore.h b/src/BlueprintParserCore.h
@@ -112,18 +112,20 @@ namespace snowcrash {
         }
     };
 
-    //
-    // Blueprint Parser Options
-    //
+    /**
+     *  \brief Blueprint Parser Options.
+     *
+     *  Controls blueprint parser behavi
+     */
     enum BlueprintParserOption {
-        RenderDescriptionsOption = (1 << 0),    // Render Markdown in description
-        RequireBlueprintNameOption = (1 << 1)   // Treat missing blueprint name as error
+        RenderDescriptionsOption = (1 << 0),    /// < Render Markdown in description.
+        RequireBlueprintNameOption = (1 << 1)   /// < Treat missing blueprint name as error
     };
     typedef unsigned int BlueprintParserOptions;
 
-    //
-    // Parser Core Data
-    //
+    /**
+     *  Parser Core Data
+     */
     struct BlueprintParserCore {
         BlueprintParserCore(BlueprintParserOptions opts,
                             const SourceData& src,
@@ -261,12 +263,14 @@ namespace snowcrash {
         return (!keyValuePair.first.empty() && !keyValuePair.second.empty());
     }
 
-    ///! \brief Checks cursor validity within its container.
-    ///! \param cur an iterator to be checked
-    ///! \param bounds boundaries to check against
-    ///! \param parent cursor's parent block to be used in case of error reporting
-    ///! \param result error result output, an error object is added in case of failed check
-    ///! \returns true if cursor appears to be valid false otherwise
+    /**
+     *  \brief Checks cursor validity within its container.
+     *  \param cur an iterator to be checked
+     *  \param bounds boundaries to check against
+     *  \param parent cursor's parent block to be used in case of error reporting
+     *  \param result error result output, an error object is added in case of failed check
+     *  \returns true if cursor appears to be valid false otherwise
+     */
     FORCEINLINE bool CheckCursor(const BlockIterator& cur,
                                  const SectionBounds& bounds,
                                  const BlockIterator& parent,

diff --git a/src/MarkdownParser.cc b/src/MarkdownParser.cc
@@ -22,7 +22,7 @@ static std::string BufText(const struct buf *text)
 
 const size_t MarkdownParser::OutputUnitSize = 64;
 const size_t MarkdownParser::MaxNesting = 16;
-const int MarkdownParser::ParserExtensions = MKDEXT_FENCED_CODE | MKDEXT_NO_INTRA_EMPHASIS /*| MKDEXT_TABLES */;
+const int MarkdownParser::ParserExtensions = MKDEXT_FENCED_CODE | MKDEXT_NO_INTRA_EMPHASIS | MKDEXT_LAX_SPACING /*| MKDEXT_TABLES */;
 
 void MarkdownParser::parse(const SourceData& source, Result& result, MarkdownBlock::Stack& markdown)
 {