Add `multiple` option to annotations #257

Closed
HugoGiraudel opened this Issue Oct 13, 2014 · 1 comment

Comments

Projects
None yet
2 participants
@HugoGiraudel
Member

HugoGiraudel commented Oct 13, 2014

Currently and from a strictly technical point of view, all annotations can appear multiple times on an item. That being said, it is wrong from a practical standpoint. Some annotations should not appear several times, for instance @type on variables, or @return on functions, only to name a few.

@FWeinb suggests we add a multiple boolean option on each annotation. This way, annotations would not always be arrays. They would be arrays if they allow multiple occurrences (i.e. multiple: true), else it would be a standalone value.

This would solve issue like:

{% if item.return %}
  {{ return[0].type }} {{ return[0].description }}
{% endif %}

... which is ugly as fuck.

This would trigger breaking changes, so it's either 2.0, or never (well, 3.0...).

Edit: this will lead to a new terminology "collection annotations" and "single annotations". I like it.

@HugoGiraudel HugoGiraudel added this to the 2.0 milestone Oct 13, 2014

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Oct 13, 2014

Member

Done in cdocparser@0.5.0 and used in scss-comment-parser@0.5.1-rc1.

For know this is only in rc1 to be able to fix bugs in scss-comment-parser before we release SassDoc 2.0.
We should make a list of annotations that can only be used once per comment.

Member

FWeinb commented Oct 13, 2014

Done in cdocparser@0.5.0 and used in scss-comment-parser@0.5.1-rc1.

For know this is only in rc1 to be able to fix bugs in scss-comment-parser before we release SassDoc 2.0.
We should make a list of annotations that can only be used once per comment.

@FWeinb FWeinb closed this Oct 13, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment