Addon-docs: Updated recipe for notes as component description

MIGRATION.md

@@ -87,6 +87,8 @@ The old behavior of `<Description of={Component} />` was to concatenate the info
 
 The new default behavior is to use the framework-specific description extractor, which for React/Vue is still docgen, but may come from other places (e.g. a JSON file) for other frameworks.
 
+The description doc block on DocsPage has also been updated. To see how to configure it in 5.3, please see [the updated recipe](https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/recipes.md#migrating-from-notesinfo-addons)
+
 ### React Native Async Storage
 
 Starting from version React Native 0.59, Async Storage is deprecated in React Native itself. The new @react-native-community/async-storage module requires native installation, and we don't want to have it as a dependency for React Native Storybook.
@@ -95,9 +97,9 @@ To avoid that now you have to manually pass asyncStorage to React Native Storybo
 
 Solution:
 
- * Use `require('@react-native-community/async-storage')` for React Native v0.59 and above.
- * Use `require('react-native').AsyncStorage` for React Native v0.58 or below.
- * Use `null` to disable Async Storage completely.
+- Use `require('@react-native-community/async-storage')` for React Native v0.59 and above.
+- Use `require('react-native').AsyncStorage` for React Native v0.58 or below.
+- Use `null` to disable Async Storage completely.
 
 ```javascript
 getStorybookUI({

addons/docs/docs/recipes.md

@@ -11,6 +11,8 @@
 - [Migrating from notes/info addons](#migrating-from-notesinfo-addons)
 - [Exporting documentation](#exporting-documentation)
 - [Disabling docs stories](#disabling-docs-stories)
+  - [DocsPage](#docspage)
+  - [MDX Stories](#mdx-stories)
 - [More resources](#more-resources)
 
 ## Component Story Format (CSF) with DocsPage
@@ -78,7 +80,7 @@ What's happening here:
 - The MDX loader is using story metadata from CSF, such as name, decorators, parameters, but will give giving preference to anything defined in the MDX file.
 - The MDX file is using the Meta `default` defined in the CSF.
 
-## CSF Stories with Arbitrary MDX
+## CSF Stories with arbitrary MDX
 
 We recommend [MDX Docs](#csf-stories-with-mdx-docs) as the most ergonomic way to annotate CSF stories with MDX. There's also a second option if you want to annotate your CSF with arbitrary markdown:
 
@@ -153,20 +155,27 @@ We made this error explicit to make sure you know what you're doing when you mix
 
 ## Migrating from notes/info addons
 
-If you're currently using the notes/info addons, you can upgrade to DocsPage [using slots](./docspage.md#docspage-slots). There are different ways to use each addon, so you can adapt this recipe according to your use case.
+If you're currently using the notes/info addons, you can upgrade to DocsPage by providing a custom `docs.extractComponentDescription` parameter. There are different ways to use each addon, so you can adapt this recipe according to your use case.
 
-Suppose you've added a `notes` parameter to each component in your library, containing markdown text, and you want that to show up at the top of the page in the `Description` slot. Then you would modify your setup in `.storybook/config.js`:
+Suppose you've added a `notes` parameter to each component in your library, containing markdown text, and you want that to show up at the top of the page in the `Description` slot. You could do that by adding the following snippet to `.storybook/config.js`:
 
 ```js
-import { DocsPage } from '@storybook/addon-docs/blocks';
+import { addParameters } from '@storybook/client-api';
 
 addParameters({
-  docs: ({ context }) => (
-    <DocsPage context={context} descriptionSlot={({ parameters }) => parameters.notes} />
-  ),
+  docs: {
+    extractComponentDescription: (component, { notes }) => {
+      if (notes) {
+        return typeof notes === 'string' ? notes : notes.markdown || notes.text;
+      }
+      return null;
+    },
+  },
 });
 ```
 
+The default `extractComponentDescription` provided by the docs preset extracts JSDoc code comments from the component source, and ignores the second argument, which is the story parameters of the currently-selected story. In contrast, the code snippet above ignores the comment and uses the notes parameter for that story.
+
 ## Exporting documentation
 
 > ⚠️ The `--docs` flag is an experimental feature in Storybook 5.2. The behavior may change in 5.3 outside of the normal semver rules. Be forewarned!

addons/docs/src/blocks/Description.tsx

@@ -55,7 +55,7 @@ ${extractComponentDescription(target) || ''}
     case DescriptionType.DOCGEN:
     case DescriptionType.AUTO:
     default:
-      return { markdown: extractComponentDescription(target) };
+      return { markdown: extractComponentDescription(target, parameters) };
   }
 };
 

addons/docs/src/blocks/DocsPage.tsx

@@ -64,12 +64,13 @@ const defaultSubtitleSlot: StringSlot = ({ parameters }) =>
 
 const defaultPropsSlot: PropsSlot = context => getPropsTableProps({ of: '.' }, context);
 
-const defaultDescriptionSlot: StringSlot = ({ parameters: { component, docs } }) => {
+const defaultDescriptionSlot: StringSlot = ({ parameters }) => {
+  const { component, docs } = parameters;
   if (!component) {
     return null;
   }
   const { extractComponentDescription } = docs || {};
-  return extractComponentDescription && extractComponentDescription(component);
+  return extractComponentDescription && extractComponentDescription(component, parameters);
 };
 
 const defaultPrimarySlot: StorySlot = stories => stories && stories[0];