Is there documentation for the parse results?

[ghost]

I've been browsing all of the different parsers in apiaryio org. After navigating to drafter or snowcrash or one of the low level parsers I think it defined the different outputs one of which led to a dead page and one that led to a deprecated warning and said that API Elements is the new standard output.

At that website it defers to individual parsers for explicit information on things like how sourceMap is used; which leads me right back to this project. An Example

So my question is if I want to use protagonist or one of the other parsers to check for errors, how do I parse the results to know where the errors/warnings are?

I intentionally created a couple of errors in my document. It looks like an annotation gets created for each. And under each there is a sourceMap.content.sourceMap that contains 2 numbers. Are those line and column (doesn't seem possible since I got a value much larger than the number of rows in my file)? or are they character position and length?

Here's an example annotation. Thanks

    {
      "element": "annotation",
      "meta": {
        "classes": {
          "element": "array",
          "content": [
            {
              "element": "string",
              "content": "warning"
            }
          ]
        }
      },
      "attributes": {
        "code": {
          "element": "number",
          "content": 1
        },
        "sourceMap": {
          "element": "array",
          "content": [
            {
              "element": "sourceMap",
              "content": [
                {
                  "element": "array",
                  "content": [
                    {
                      "element": "number",
                      "content": 0
                    },
                    {
                      "element": "number",
                      "content": 12
                    }
                  ]
                }
              ]
            }
          ]
        }
      },
      "content": "expected API name, e.g. '# <API Name>'"
    }

[ghost]

https://github.com/apiaryio/drafter defines the two outputs:

• Parse Result Namespace which leads to "sorry page does not exist" page.

• API Blueprint AST which is deprecated. Clicking that link leads you to API Elements.

[ghost]

Finally, can I assume there were no errors/warnings if there are no annotations in the resulting JSON?

[kylef]

Hi @mgwelch, we re-hauled the API Elements documentation and must've forgot about some of the links here.

You can find the docs at http://apielements.org, the example element reference page breaks down all of the elements including parse result. There is also a tooling page if you are trying to consume the output in JavaScript check out the API Elements JS package, there is a Python library listed.

Finally, can I assume there were no errors/warnings if there are no annotations in the resulting JSON?

That's correct.

[kylef]

Realise this was posted on Protagonist and not Drafter. In that case I'd recommend you check out the Fury (https://github.com/apiaryio/fury.js), and Fury adapter for API Blueprint (http://github.com/apiaryio/fury-adapter-apib-parser). That provides a JavaScript API (https://api-elements-js.readthedocs.io/en/latest/api.html#parse-result) to go over the parse result.

[ghost]

@kylef Thanks for your quick response.

Upon reviewing the API Elements documentation more closely I found the relevant information: https://api-elements.readthedocs.io/en/latest/element-definitions.html#source-map

Thanks.

[ghost]

One last question then. I see how I got confused original. If you look at Annotation the descriptions for code and sourceMap are vague:

code (Number) - Parser-specific code of the annotation. Refer to parser documentation for explanation of the codes.
sourceMap (Array[Source Map]) - Locations of the annotation in the source file.

I've now found the Source Map information. Is there a definition for code elsewhere that I'm missing. All we're told is it's a Number and I must refer to the parser information. So does that mean I go back to drafter or snowcrash for more info?

[ghost]

Looks like I'm well on my way. Still curious if I can learn anything more about code but its not super critical. The index along with src-location framework allows me to report out line and column of any issues.

[kylef]

The codes are defined in snowcrash source: https://github.com/apiaryio/drafter/blob/e83e2fd48ef647bb525e5a95ddaef52c9306ed6b/ext/snowcrash/src/SourceAnnotation.h#L100-L136.

I was proposing that we should remove codes and replace with URLs in apiaryio/api-elements#24, would welcome any input in that issue if you have some thoughts on this as you are trying ot make sense of these annotation codes.

We've also added line and column numbers if it helps in #219.