Remove `annotation` code about api-elements HOT 7 OPEN

I am definitely up for it, I find the links being very useful because not always the error message is clear enough and further info is needed. although I think we should make an attempt to unify the codes as well. I think that a general categorization of the warnings/errors is useful for tools using the parse result.

from api-elements.

although I think we should make an attempt to unify the codes as well

@w-vi Would we still need to provide error codes if the profile/origin link can replace their purpose? I was proposing we remove the code completely.

from api-elements.

I was personally not a fan of the codes, and I agree that the links provide the same functionality with a lot more flexibility. So I think you can capture the same info and more with links.

I think the part that will take some work is keeping the links pointing to the correct places. This is because some annotations will be parser specific rather than related to API Elements itself. But the profile link example you have above is a good one where you can fit generic errors/warnings/info into the API Elements spec itself that may be reused by tooling.

from api-elements.

Codes are convenient for programmatic approach, sure I can match the strings of the link to distinguish between warning error etc but then I need to know the errors/warnings beforehand as from the new annotation I have no idea what is it as in how I know that this is an error and not just some informational warning. To clarify, we should use codes more for categories of errors/warnings and not as the code being a sole identifier of an error.

from api-elements.

Seems like it might work well to use classes instead of codes for those generic purposes.

from api-elements.

Seems like it might work well to use classes instead of codes for those generic purposes.

That sounds good to me.

I was going by the example in Swagger adapter where the origin links have a 1-1 mapping between codes for all URLs except one (https://github.com/apiaryio/fury-adapter-swagger/blob/master/src/annotations.js#L17) the fragment is placed into the URL.

from api-elements.

classes are good too. My main point is that I'd like to keep some generic way how tools can handle annotations and that those classes or codes or whatever should be unified in all parsers.

from api-elements.