add docs and cookbook example on visibleName tag

Author: glebez

docs/Cookbook.md

@@ -25,6 +25,7 @@
 * [How to add fonts from Google Fonts?](#how-to-add-fonts-from-google-fonts)
 * [How to reuse project’s webpack config?](#how-to-reuse-projects-webpack-config)
 * [How to use React Styleguidist with Redux, Relay or Styled Components?](#how-to-use-react-styleguidist-with-redux-relay-or-styled-components)
+* [How to change the names of components displayed in Styleguidist UI?](#how-to-change-the-names-of-components-displayed-in-styleguidist-ui)
 * [What’s the difference between Styleguidist and Storybook?](#whats-the-difference-between-styleguidist-and-storybook)
 * [Are there any other projects like this?](#are-there-any-other-projects-like-this)
 
@@ -479,6 +480,29 @@ See in [configuring webpack](Webpack.md#reusing-your-projects-webpack-config).
 
 See [working with third-party libraries](Thirdparties.md).
 
+## How to change the names of components displayed in Styleguidist UI?
+
+Often you might want to change your components' names to be displayed differently, for example, for stylistic purposes or to give them a more descriptive names in your styleguide.
+
+This can be done by adding [@visibleName](Documenting.md#-visiblename-custom-tag) tag to your component documentation.
+
+In case you want to change components' names in bulk, for example, based on their current name, you can utilize [updateDocs](Configuration.md#updatedocs) configuration option.
+
+Here's an example of how this can be achieved:
+
+```javascript
+const _ = require('lodash')
+
+module.exports = {
+  updateDocs(docs) {
+    if (docs && docs.displayName) {
+      docs.visibleName = _.lowerCase(docs.displayName)
+    }
+    return docs
+  }
+}
+```
+
 ## What’s the difference between Styleguidist and Storybook?
 
 Both tools are good and mature, they have many similarities but also some distinctions that may make you choose one or the other. For me the biggest distinction is how you describe component variations.

docs/Documenting.md

@@ -152,6 +152,7 @@ You can use the following [JSDoc](http://usejsdoc.org/) tags when documenting co
 * [@author](http://usejsdoc.org/tags-author.html)
 * [@since](http://usejsdoc.org/tags-since.html)
 * [@version](http://usejsdoc.org/tags-version.html)
+* [@visibleName](#-visiblename-custom-tag)
 
 When documenting props you can also use:
 
@@ -203,6 +204,23 @@ class Button extends React.Component {
 }
 ```
 
+### @visibleName custom tag
+
+Apart from most of the jsDocs tags that can be used with RSG, @visibleName is not present in jsDoc specs. This is a custom tag, that we have added to provide users with a way to define names for components to be used in the UI.
+
+Let's take a look at the example:
+
+```javascript
+/**
+ * The only true button.
+ *
+ * @visibleName The Best Button Ever 🐙
+ */
+class Button extends React.Component {
+```
+
+By defining the @visibleName tag above, you let the Styleguidist know that this name should be used whenever the component is displayed in the UI as 'The Best Button Ever 🐙' instead of it's original 'Button' name.
+
 ## Writing code examples
 
 Code examples in Markdown use ES6+JSX syntax. All components covered by the style guide can be used in all examples: