diff --git a/src-docs/src/views/mutation_observer/mutation_observer_example.js b/src-docs/src/views/mutation_observer/mutation_observer_example.js
index 53177e9c851f..9357ea629fd9 100644
--- a/src-docs/src/views/mutation_observer/mutation_observer_example.js
+++ b/src-docs/src/views/mutation_observer/mutation_observer_example.js
@@ -8,6 +8,7 @@ import {
 
 import {
   EuiCode,
+  EuiLink,
   EuiMutationObserver,
 } from '../../../../src/components';
 
@@ -28,8 +29,11 @@ export const MutationObserverExample = {
     }],
     text: (
       <p>
-        <EuiCode>MutationObserver</EuiCode> is a wrapper around the Mutation Observer API.
-        It takes the same configuration object describing what to watch for and fires the
+        <EuiCode>MutationObserver</EuiCode> is a wrapper around the
+        <EuiLink href="https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver"> Mutation Observer API </EuiLink>
+        which allows watching for DOM changes to elements and their children.
+        <EuiCode>MutationObserver</EuiCode> takes the same configuration object
+        as the browser API to describe what to watch for, and fires the
         callback when that mutation happens.
       </p>
     ),
diff --git a/src-docs/src/views/popover/popover_example.js b/src-docs/src/views/popover/popover_example.js
index 356ad0fee10d..4b86b9d15ed6 100644
--- a/src-docs/src/views/popover/popover_example.js
+++ b/src-docs/src/views/popover/popover_example.js
@@ -41,8 +41,8 @@ const popoverHTMLElementAnchorSource = require('!!raw-loader!./popover_htmleleme
 const popoverHTMLElementAnchorHtml = renderToHtml(PopoverHTMLElementAnchor);
 
 import PopoverContainer from './popover_container';
-const popoverContainerSource = require('!!raw-loader!./popover_htmlelement_anchor');
-const popoverContainerHtml = renderToHtml(PopoverHTMLElementAnchor);
+const popoverContainerSource = require('!!raw-loader!./popover_container');
+const popoverContainerHtml = renderToHtml(PopoverContainer);
 
 
 export const PopoverExample = {
diff --git a/src-docs/src/views/portal/portal_example.js b/src-docs/src/views/portal/portal_example.js
index b720d56ed69f..35aa1ef714b7 100644
--- a/src-docs/src/views/portal/portal_example.js
+++ b/src-docs/src/views/portal/portal_example.js
@@ -49,13 +49,22 @@ export const PortalExample = {
       code: portalInsertHtml,
     }],
     text: (
-      <p>
-        There is an optional <EuiCode>insert</EuiCode> prop that can specify the portal&quot;s
-        location in the DOM. When used, it is important to consider how the location relates
-        to the component lifecycle, as it could be removed from the DOM by another component
-        update.
-      </p>
+      <React.Fragment>
+        <p>
+          There is an optional <EuiCode>insert</EuiCode> prop that can specify the portal&apos;s
+          location in the DOM. When used, it is important to consider how the location relates
+          to the component lifecycle, as it could be removed from the DOM by another component
+          update.
+        </p>
+        <p>
+          <EuiCode>insert</EuiCode> is an object with two key/values: <EuiCode>sibling</EuiCode>
+          and <EuiCode>position</EuiCode>. sibling is either the React node or HTMLElement
+          the portal should be inserted next to, and position specifies the portals relative
+          position, either <EuiCode>before</EuiCode> or <EuiCode>after</EuiCode>.
+        </p>
+      </React.Fragment>
     ),
+    props: { EuiPortal },
     demo: <PortalInsert />,
   }],
 };
diff --git a/src-docs/src/views/portal/portal_insert.js b/src-docs/src/views/portal/portal_insert.js
index 06a8cd66bcb3..574f1969d4f5 100644
--- a/src-docs/src/views/portal/portal_insert.js
+++ b/src-docs/src/views/portal/portal_insert.js
@@ -19,11 +19,11 @@ export class PortalInsert extends Component {
     };
   }
 
-  setButtonRef = node => this.buttonRef = node
+  setButtonRef = node => this.buttonRef = node;
 
   togglePortal = () => {
     this.setState(prevState => ({ isPortalVisible: !prevState.isPortalVisible }));
-  }
+  };
 
   render() {
 
diff --git a/src/components/portal/portal.js b/src/components/portal/portal.js
index 7dd75de5cf7f..c7f3f8acc38d 100644
--- a/src/components/portal/portal.js
+++ b/src/components/portal/portal.js
@@ -63,12 +63,13 @@ export class EuiPortal extends Component {
 
 EuiPortal.propTypes = {
   children: PropTypes.node,
+  /** `{sibling: ReactNode|HTMLElement, position: 'before'|'after'}` */
   insert: PropTypes.shape({
     sibling: PropTypes.oneOfType([
       PropTypes.node,
       PropTypes.instanceOf(HTMLElement)
     ]).isRequired,
     position: PropTypes.oneOf(INSERT_POSITIONS),
-    portalRef: PropTypes.func,
-  })
+  }),
+  portalRef: PropTypes.func,
 };