Confusing AST for enum examples about drafter

[tjanc]

I'm interested, in what way is this behavior a regression/bug? What is it breaking?

Admittedly, this transformation is confusing, but I don't understand how it's incorrect. Does the emitted API Elements fail to represent the data structure given to drafter in MSON?

• The sample is an enum, which is of the type of what we are providing a sample for.
• The sample enum's content is not just any string value (i.e. without fixed), but the one and only free value (i.e. with fixed).

---

Also note that the output of drafter, API Elements, is by no means an Abstract Syntax Tree (AST) for API Blueprint.

[goganchic]

@tjanc I don't mean that it's a bug or regression. Actually you are right, it's confusing behaviour.

[tjanc]

We were toying with the idea of saying that samples/default are interpreted as fixed in API Elements by default. If I recall correctly, we dropped that mainly because of three reasons:

• it adds a point of contextual interpretation (you need to know whether the element is a sample to interpret it), adding confusion
• fixed behaves differently on array and object compared to other types, more confusion
• perhaps in the future we want to have second order types in APIE; a sample then would be something more than a value; that's why always fixing every sample to a single value might close some doors on us

That said, I don't really see a reason why we shouldn't put the string directly into samples (without a wrapping enum). My reasoning there was probably to have the type of the sample match the type of the element one to one, but that might be an unnecessary requirement.

@pksunkara What's your take on this?

[goganchic]

it adds a point of contextual interpretation (you need to know whether the element is a sample to interpret it), adding confusion

Actually I can't understand your point. Do you mean that such AST could be interpreted without any context?

                              element: "enum"
                              content:
                                element: "string"
                                attributes:
                                  typeAttributes:
                                    element: "array"
                                    content:
                                      -
                                        element: "string"
                                        content: "fixed"
                                content: "free"

If I'm not mistaken this part is the same for enum with one element and enum example, so you need a bit of context to understand what is it.

fixed behaves differently on array and object compared to other types, more confusion

Could you please explain your point a bit more?

perhaps in the future we want to have second order types in APIE

What is second order types in this context?