Add selector annotations to SASSDoc for #23 and applied annotations t…

…o components

.sassdocrc

@@ -5,10 +5,11 @@
 	],
 	"display": {
 		"annotations": {
-			"function": ["description", "return", "throw", "require", "usedby", "since", "see", "todo", "link", "author"],
-			"mixin": ["description", "content", "output", "throw", "require", "usedby", "since", "see", "todo", "link", "author"],
-			"placeholder": ["description", "example", "throw", "require", "usedby", "since", "see", "todo", "link", "author"],
-			"variable": ["description", "type", "require", "example", "usedby", "since", "see", "todo", "link", "author"]
+			"function": ["description", "return", "throw", "require", "usedby", "since", "see", "todo", "link"],
+			"mixin": ["description", "content", "output", "throw", "require", "usedby", "since", "see", "todo", "link"],
+			"placeholder": ["description", "example", "throw", "require", "usedby", "since", "see", "todo", "link"],
+			"variable": ["description", "type", "require", "example", "usedby", "since", "see", "todo", "link"],
+			"css": ["description", "require", "usedby", "since", "see", "todo", "link"]
 		},
 		"access": ["public", "private"],
 		"alias": false,

src/stylesheets/components/_components-maintain-ratio.scss

@@ -9,15 +9,15 @@
 /// Automatically applies to `iframe`, `embed`, `object` and `video` tags.
 /// Alternatively, you can use the `__item` selector to specify the element directly.
 ///
-/// Modifiers:
+/// BEM elements:
+///   - `__item`
+///
+/// BEM modifiers:
 ///   - `--21-9`
 ///   - `--16-9`
 ///   - `--4-3`
 ///   - `--square`
 ///
-/// Elements:
-///   - `__item`
-///
 /// @example html - Sixteen by nine example
 ///   <div class="maintain-ratio maintain-ratio--16-9">
 ///     <iframe src="https://www.youtube.com/embed/FTQbiNvZqaY" allowfullscreen></iframe>

src/stylesheets/components/_components-phase.scss

@@ -3,7 +3,14 @@
 ////
 
 /// A phase banner includes a tag and a label and is designed
-/// to designate that a service is in alpha or beta
+/// to designate that a service is in alpha or beta.
+/// Usually contains a `.phase-tag`.
+///
+/// BEM elements:
+///   - `__tag`   The tag itself
+///   - `__label` The label explaining
+///
+/// @see .phase-tag
 .phase-banner {
   border-bottom: 1px solid $colour-border;
   display: table;
@@ -26,6 +33,15 @@
 
 /// A coloured block to designate a service being in alpha or beta. Can be
 /// used on its own but usually used within a `.phase-banner`.
+///
+/// BEM modifiers:
+///   - `--alpha` Alpha
+///   - `--beta`  Beta
+///   - `--live`  Live
+///
+/// @todo Distinguish private beta/public beta
+/// @todo Do we also need a discover phase colour?
+///
 /// @see .phase-banner
 .phase-tag {
   background-color: get-colour(grey, mid-dark);

src/stylesheets/components/_components-tabs.scss

@@ -4,13 +4,15 @@
 
 /// Tabbed navigational structure
 ///
-/// Elements:
+/// BEM elements:
 ///   - `__list`    The containing list of tabs
 ///   - `__tab`     An individual tab
 ///   - `__tab-btn` A button within a tab
 ///   - `__content` The tabs content - container for the
 ///   - `__pane`    An individual tab pane
 ///
+/// @todo Tabs on mobile devices
+///
 /// @example html
 ///   <div class="tabs" data-tabs>
 ///     <ul class="tabs__list" role="tablist">

web/server/controllers/sass.js

@@ -45,7 +45,8 @@ router.get("/docs/:section", function(req, res, next) {
 			groupId: req.params.section,
 			groupName: group,
 			items: items,
-			byType: data.byGroupAndType[req.params.section]
+			byType: data.byGroupAndType[req.params.section],
+			display: data.display
 		};
 		res.render("sass/docs-group", pageData);
 	}

web/server/views/sass/includes/annotations/preview.njk

@@ -1,7 +1,7 @@
 {# CSS Selectors #}
 {% if item.context.type == "css" %}
 
-	CSS Selector: {{ item.context.name }}
+	{# NOOP #}
 
 {# Placeholders #}
 {% elif item.context.type == "placeholder" %}

web/server/views/sass/includes/annotations/see.njk

@@ -1,6 +1,6 @@
-{% if item.see.length > 1 %}
+{% if item.see.length >= 1 %}
 	<div class="grid__item one-whole tablet--one-half desktop--one-third">
-		<h5>See</h5>
+		<h5>See also</h5>
 
 		<ul>
 			{% for see in item.see %}

web/server/views/sass/includes/annotations/todo.njk

@@ -1,10 +1,10 @@
 {% if item.todo.length > 0 %}
 	<div class="grid__item one-whole tablet--one-half desktop--one-third">
-		<h5>TODO's</h5>
+		<h5>TODO</h5>
 
 		<ul>
 			{% for todo in item.todo %}
-				<li>{{ todo|safe }}</li>
+				<li>{{ todo | striptags }}</li>
 			{% endfor %}
 		</ul>
 	</div>