docs: fix escape issue (#248)

* docs: fixing @ escape issue in JSDoc

* fixing jsdoc-to-markdown caching issue

* Fixing transforms.hbs

.jsdoc.json

@@ -0,0 +1,3 @@
+{
+  "plugins": ["./node_modules/jsdoc-escape-at"]
+}

CONTRIBUTING.md

@@ -58,6 +58,22 @@ Any new features should implement the proper unit tests. We use Jest to test our
 
 If you are adding a new transform, action, or format: please add new unit tests. You can see examples in test/formats.
 
+## Documentation
+
+We use [JSDoc](http://usejsdoc.org) comments in all of the code, including built-in formats and transforms, to document all of the functionality of Style Dictionary. If you are adding a new function or changing how something works, please update the JSDoc comments.
+
+We use [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown) to create markdown files based on JSDoc comments in the code. These markdown files get generated in the docs/ directory. To see what is happening, take a look at [scripts/generateDocs.js](scripts/generateDocs.js). This file is run when the npm script `generate-docs` is run, which happens whenever we do an npm release. This script generates:
+  * docs/actions.md
+  * docs/api.md
+  * docs/formats.md
+  * docs/transform_groups.md
+  * docs/transforms.md
+
+Each of these files uses a handlebars template in scripts/handlebars/templates and jsdoc-to-markdown to generate the respective markdown file.
+
+There are other markdown files in the [docs/](docs/) directory that are plain markdown files. You can edit any of those like normal.
+
+We use [docsify](https://docsify.js.org/#/) to transform the markdown files into a documentation website. To preview it locally, run `npm run serve-docs`.
 
 [issues]: https://github.com/amzn/style-dictionary/issues
 [pr]: https://github.com/amzn/style-dictionary/pulls

docs/actions.md

@@ -1,3 +1,7 @@
+<!--
+DO NOT EDIT THIS FILE DIRECTLY, THIS FILE IS GENERATED BY JSDOC!
+EDIT scripts/handlebars/templates/api.hbs OR JSDOC COMMENT INSTEAD!
+-->
 # Actions
 
 Actions provide a way to run custom build code such as generating binary assets like images.
@@ -26,18 +30,19 @@ You use actions in your config file under platforms > [platform] > actions
 
 [lib/common/actions.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/actions.js)
 
-### android/copyImages
+### android/copyImages 
 
 
 Action to copy images into appropriate android directories.
 
 
 * * *
 
-### copy_assets
+### copy_assets 
 
 
 Action that copies everything in the assets directory to a new assets directory in the build path of the platform.
 
 
 * * *
+

docs/api.md

@@ -1,3 +1,7 @@
+<!--
+DO NOT EDIT THIS FILE DIRECTLY, THIS FILE IS GENERATED BY JSDOC!
+EDIT scripts/handlebars/templates/api.hbs OR JSDOC COMMENT INSTEAD!
+-->
 # API
 
 ### buildAllPlatforms 
@@ -175,7 +179,7 @@ StyleDictionary.registerAction({
 
 * * *
 
-### registerFilter
+### registerFilter 
 > StyleDictionary.registerFilter(filter) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)
 
 
@@ -188,21 +192,21 @@ Add a custom filter to the style dictionary
 | --- | --- | --- |
 | filter | <code>Object</code> |  |
 | filter.name | <code>String</code> | Name of the filter to be referenced in your config.json |
-| filter.matcher | <code>function</code> | Matcher function, return boolean if filter should be applied. |
+| filter.matcher | <code>function</code> | Matcher function, return boolean if the property should be included. |
 
-**Example**
+**Example**  
 ```js
 StyleDictionary.registerFilter({
   name: 'isColor',
   matcher: function(prop) {
-    return return prop.attributes.category === 'color';
+    return prop.attributes.category === 'color';
   }
 })
 ```
 
 * * *
 
-### registerFormat
+### registerFormat 
 > StyleDictionary.registerFormat(format) ⇒ [<code>style-dictionary</code>](#module_style-dictionary)