From ecd9a41611e75ffca09ebada1c28f66f5a872030 Mon Sep 17 00:00:00 2001
From: Michael Shilman <michael@lab80.co>
Date: Sun, 2 Aug 2020 19:58:34 +0800
Subject: [PATCH] Addon-docs: Add docs.description parameter

---
 MIGRATION.md                                  | 21 ++++++++++
 addons/docs/src/blocks/Description.tsx        |  9 ++++-
 addons/docs/src/blocks/DocsContainer.tsx      | 17 ++++----
 addons/docs/src/blocks/DocsStory.tsx          | 40 ++++++++++++++-----
 .../stories/demo/button.stories.js            |  7 +++-
 5 files changed, 74 insertions(+), 20 deletions(-)

diff --git a/MIGRATION.md b/MIGRATION.md
index 3f71aa3945f4..07fa885f8e2c 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -13,6 +13,7 @@
     - [DocsPage slots removed](#docspage-slots-removed)
     - [React prop tables with Typescript](#react-prop-tables-with-typescript)
     - [ConfigureJSX true by default in React](#configurejsx-true-by-default-in-react)
+    - [Docs description parameter](#docs-description-parameter)
   - [New addon presets](#new-addon-presets)
   - [Removed babel-preset-vue from Vue preset](#removed-babel-preset-vue-from-vue-preset)
   - [Removed Deprecated APIs](#removed-deprecated-apis)
@@ -284,6 +285,26 @@ module.exports = {
 };
 ```
 
+#### Docs description parameter
+
+In 6.0, you can customize a component description using the `docs.description.component` parameter, and a story description using `docs.description.story` parameter.
+
+Example:
+
+```js
+import { Button } from './Button';
+
+export default {
+  title: 'Button'
+  parameters: { docs: { description: { component: 'some component **markdown**' }}}
+}
+
+export const Basic = () => <Button />
+Basic.parameters = { docs: { description: { story: 'some story **markdown**' }}}
+```
+
+In 5.3 you customized a story description with the `docs.storyDescription` parameter. This has been deprecated, and support will be removed in 7.0.
+
 ### New addon presets
 
 In Storybook 5.3 we introduced a declarative [main.js configuration](#to-mainjs-configuration), which is now the recommended way to configure Storybook. Part of the change is a simplified syntax for registering addons, which in 6.0 automatically registers many addons _using a preset_, which is a slightly different behavior than in earlier versions.
diff --git a/addons/docs/src/blocks/Description.tsx b/addons/docs/src/blocks/Description.tsx
index 520b62632364..f8bf8e711db0 100644
--- a/addons/docs/src/blocks/Description.tsx
+++ b/addons/docs/src/blocks/Description.tsx
@@ -37,8 +37,15 @@ export const getDescriptionProps = (
     return { markdown: children || markdown };
   }
   const { component, notes, info, docs } = parameters;
-  const { extractComponentDescription = noDescription } = docs || {};
+  const { extractComponentDescription = noDescription, description } = docs || {};
   const target = of === CURRENT_SELECTION ? component : of;
+
+  // override component description
+  const componentDescriptionParameter = description?.component;
+  if (componentDescriptionParameter) {
+    return { markdown: componentDescriptionParameter };
+  }
+
   switch (type) {
     case DescriptionType.INFO:
       return { markdown: getInfo(info) };
diff --git a/addons/docs/src/blocks/DocsContainer.tsx b/addons/docs/src/blocks/DocsContainer.tsx
index ecaaa01f62cc..2052b510a60d 100644
--- a/addons/docs/src/blocks/DocsContainer.tsx
+++ b/addons/docs/src/blocks/DocsContainer.tsx
@@ -24,18 +24,21 @@ const defaultComponents = {
   ...HeadersMdx,
 };
 
+const warnOptionsTheme = deprecate(
+  () => {},
+  dedent`
+    Deprecated parameter: options.theme => docs.theme
+    
+    https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/theming.md#storybook-theming
+`
+);
+
 export const DocsContainer: FunctionComponent<DocsContainerProps> = ({ context, children }) => {
   const { id: storyId = null, parameters = {} } = context || {};
   const { options = {}, docs = {} } = parameters;
   let themeVars = docs.theme;
   if (!themeVars && options.theme) {
-    deprecate(
-      () => {},
-      dedent`
-        options.theme => Deprecated: use  story.parameters.docs.theme instead.
-        See https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/theming.md#storybook-theming for details.
-    `
-    )();
+    warnOptionsTheme();
     themeVars = options.theme;
   }
   const theme = ensureTheme(themeVars);
diff --git a/addons/docs/src/blocks/DocsStory.tsx b/addons/docs/src/blocks/DocsStory.tsx
index 5ce3ef4a0d4e..4eab78e0d890 100644
--- a/addons/docs/src/blocks/DocsStory.tsx
+++ b/addons/docs/src/blocks/DocsStory.tsx
@@ -1,4 +1,6 @@
 import React, { FunctionComponent } from 'react';
+import deprecate from 'util-deprecate';
+import dedent from 'ts-dedent';
 import { Subheading } from './Subheading';
 import { DocsStoryProps } from './types';
 import { Anchor } from './Anchor';
@@ -6,20 +8,36 @@ import { Description } from './Description';
 import { Story } from './Story';
 import { Canvas } from './Canvas';
 
+const warnStoryDescription = deprecate(
+  () => {},
+  dedent`
+    Deprecated parameter: docs.storyDescription => docs.description.story
+      
+    https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#docs-description-parameter
+  `
+);
+
 export const DocsStory: FunctionComponent<DocsStoryProps> = ({
   id,
   name,
   expanded = true,
   withToolbar = false,
   parameters,
-}) => (
-  <Anchor storyId={id}>
-    {expanded && <Subheading>{name}</Subheading>}
-    {expanded && parameters && parameters.docs && parameters.docs.storyDescription && (
-      <Description markdown={parameters.docs.storyDescription} />
-    )}
-    <Canvas withToolbar={withToolbar}>
-      <Story id={id} />
-    </Canvas>
-  </Anchor>
-);
+}) => {
+  let description = expanded && parameters?.docs?.description?.story;
+  if (!description) {
+    description = parameters?.docs?.storyDescription;
+    if (description) warnStoryDescription();
+  }
+  const subheading = expanded && name;
+
+  return (
+    <Anchor storyId={id}>
+      {subheading && <Subheading>{subheading}</Subheading>}
+      {description && <Description markdown={description} />}
+      <Canvas withToolbar={withToolbar}>
+        <Story id={id} />
+      </Canvas>
+    </Anchor>
+  );
+};
diff --git a/examples/official-storybook/stories/demo/button.stories.js b/examples/official-storybook/stories/demo/button.stories.js
index 710489cf5cfe..929300d2d9fc 100644
--- a/examples/official-storybook/stories/demo/button.stories.js
+++ b/examples/official-storybook/stories/demo/button.stories.js
@@ -9,6 +9,9 @@ export default {
   parameters: {
     docs: {
       inlineStories: false,
+      description: {
+        component: 'Component description **markdown** override',
+      },
     },
   },
 };
@@ -35,6 +38,8 @@ WithCounter.storyName = 'with counter';
 
 WithCounter.parameters = {
   docs: {
-    storyDescription: 'This demonstrates react hooks working inside stories. Go team! 🚀',
+    description: {
+      story: 'This demonstrates react hooks working inside stories. **Go team!** 🚀',
+    },
   },
 };