Support for comments

[AlexGrafe]

From what I saw on apiary.io I can't comment out blocks of the documentation which is very important for me.
Even putting HTML style <!-- ... --> comments doesn't work.

[zdne]

Hey @xanderiel I am trying to avoid introducing comments to the API Blueprint – as I believe that could lead to blueprints fragmentation. However I would like to know about your use case for them – perhaps we will be able to address it in a different way ?

[zdne]

Please reopen with some additional input if needed.

[toobulkeh]

👍
We'd like to use comments to save work-in-progress. Since it is a single file documentation style, I think some kind of WIP format would be helpful.

[zdne]

@toobulkeh Is your WIP about the description or the layout of APIs ? Could there be another way to satisfy it?

[mx-c]

Hi there,

I think the possibility to create comments is really important. Below 2 use case:

1. junior readers
   Some of the people who are going to use the api may need some extra info, which is not to be displayed but that would help to write documentation consistently.
2. private sections
   In my case, it is very important to be able to create private sections. That is, parts of the documentation that are not to be published to the open world. It may be an unstable endpoint, which exists but only for a brief period of time.

I refuse to create 2 separate documentations, as it is the best way to async docs. Instead, I am using comments to indicate parts that are to be preprocessed before sent to apiary. example:

<!-- <dev> -->

### Create Foo [POST]

Create a foo.  This is not yet disclosed.

+ Parameters
    + account_id (number) - Id of the account

+ Request

    + Headers

            Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

    + Body

            {
                "label": "foo fighter"
            }

+ Response 200 (application/json)

        {
            "success": true
        }
<!-- </dev> -->

A script preprocesses the input.apib file and removes the parts for the public. However, we are able to have an internal doc that documents this endpoint.

On my side, the works both on apiary and local, and it is a blessing ;). However, I just wish that in code parts, it was not considered as a syntax error but as an intended design.

[weaselmetal]

We are working on a larger api spec and use gulp inclusion, templates, hercule etc. Comments would help explain what's happening, why and how.

[zdne]

@weaselmetal that makes sense

[nayanbhana]

+1

[chano]

+1

[dcaron]

+1

[jasonwatt]

+1

[dougchase]

+1

[jancurn]

+1

FYI, we'd like to put a reference to the constants from our codebase to the API blueprint, so that when we change the constant, we can track its presence in the API blueprint. For example:

Note that the maximum length of the tag string is
64 characters <!-- =EXECUTION_TAG_MAX_LENGTH -->.
You will receive an error if you try to use a longer string.

[bovin-a]

+1

[mitchellporter]

+1

[xrochoa]

+1

[BrunoQuaresma]

+1

[Vratislav]

+1

[grellyd]

+1

[DavidBM]

+1

[vioan]

+1

[wopian]

👍

This is really useful while writing documentation from scratch. As far as i'm aware there's still no way of making comments for myself to remind me what resources are in each route, so that I know what I need to include when getting around to writing docs for them & don't miss anything. E.g:

jsonapi_resources :groups
jsonapi_resources :group_members
post '/group-invites/:id/_decline', to: 'group_invites#decline'
get '/groups/:id/_stats', to: 'groups#stats'

Only way to do it right now is to fill the documentation with useless information for developers...or just not do it and hope for the best 😅

[sureshkamidi]

For the WIP, the comment section will be very useful.

[johana-star]

➕ 1️⃣

I'd like to be able to leave comments because I want my teammates and future maintainers of the documentation to know what code the docs are based on, for example: <!-- The Whitelisted Attributes are defined in FooBar::Buzz#WHITELIST --> would save them time from searching the codebase if for any reason the docs and the code get out of sync.

[dionb]

I am using apiary for both internal specification for our devs building the api and for providing documentation to devs at other companies consuming our api.
Comments would be useful to me so that I can leave more detailed instructions than just a data structure. I would also like to be able annotate responses and provide a list of possible responses for a single error code so that I can document causes for different error codes and the expected behaviour for handling them.
Inline comments in data structures would also be good for describing the function that different options perform. eg: We do video streaming services, and we have a field in some structures that can take the values "push" and "pull" to describe how the media is intended to leave our servers. Currently this requires separate documentation

[barrynorman]

+1

[hampusiggstrom]

+1

[icapuccio]

+1

[crwh05]

+1

[jars]

+1

[skalee]

@weaselmetal wrote:

We are working on a larger api spec and use gulp inclusion, templates, hercule etc. Comments would help explain what's happening, why and how.

If you compile blueprint from smaller files, then you can remove comments at the end of build process. A JavaScript-compatible regular expression for HTML comment is <!--[\s\S]*?-->.

[Alexorz]

+1

[kylef]

We understand this is a wanted feature, but next time please use GitHub Reactions to express your feelings. Thanks! ✨

By the way, one of the benefits is we can sort by the reactions:

[kylef]

I'd like to provide some insight into what the next steps are for this feature. Right now we are constrained by our underlying markdown parser (Sundown) which has various limitations, including #207. Sundown has not been maintained since 2012 other than our changes in our own fork.

Our long term plan is to handle parsing ourselves in the API Blueprint parser which will give us a lot more control and unlock adding features like #139 and #207. While I am not able to give any timeline, it is something we are actively working towards, there are a lot of refactoring going on at the moment which is going to allow us to move forward in this area. Once the refactoring is completely we will be able to move much faster. I appreciate all of your patience.

[johana-star]

Thank you for the update @kylef.

[skalee]

Here's a working example how to remove HTML comments (<!-- -->) from resulting APIB when compiling a large APIB from smaller chunks with Hercule: https://github.com/riboseinc/ribose-api/blob/7e43af45b1d0a3fdaa6d21d982c9b5796707d3d4/bin/build.js.

[sevenate]

Any updates guys?

Would be great to know if/when this feature will be included to the official roadmap.

[jonnyijapan]

Sundown has not been maintained since 2012 other than our changes in our own fork.

Past sunset then 🌞

[tomasfejfar]

For me a great usecase would be to dump the API call that made the code sample, so that it's repeatable when the response changes.

##Update or delete [/v2/storage/triggers/{id}]
###Update [PUT]
Updates an existing trigger
+ Parameters
    + id (required, number) - Id of trigger you want to update
...
+ Response 200 (application/json) 
// /v2/storage/triggers/3?include=tables,columns  <------ when you run this on our sample 
                                                          project you get the response below. 
                                                          So when you make a change to the 
                                                          response just call this URL and replace
                                                          the response below to make docs 
                                                          up-to-date

        {
            "id": "3",
            ...
        }

[MykhailoMe]

Hello there,
Is there any update/info about such option to comment out (hide some block of documentation in MSON)?
Thanks!