fix: prefer the first description when multiple are detected (#1650)

fern-api · Oct 11, 2024 · 62a7f30 · 62a7f30
1 parent ba170fa
commit 62a7f30
Show file tree

Hide file tree

Showing 4 changed files with 60 additions and 9 deletions.
diff --git a/packages/ui/app/src/api-reference/endpoints/EndpointParameter.tsx b/packages/ui/app/src/api-reference/endpoints/EndpointParameter.tsx
@@ -5,7 +5,8 @@ import * as FernNavigation from "@fern-api/fdr-sdk/navigation";
 import { EMPTY_ARRAY } from "@fern-api/ui-core-utils";
 import cn from "clsx";
 import { compact } from "lodash-es";
-import { FC, PropsWithChildren, ReactNode, memo, useRef, useState } from "react";
+import { FC, PropsWithChildren, ReactNode, memo, useEffect, useRef, useState } from "react";
+import { capturePosthogEvent } from "../../analytics/posthog";
 import { useIsApiReferencePaginated, useRouteListener } from "../../atoms";
 import { FernAnchor } from "../../components/FernAnchor";
 import { useHref } from "../../hooks/useHref";
@@ -98,6 +99,21 @@ export const EndpointParameterContent: FC<PropsWithChildren<EndpointParameter.Co
     });
 
     const href = useHref(slug, anchorId);
+    const descriptions = compact([description, ...additionalDescriptions]);
+
+    useEffect(() => {
+        if (descriptions.length > 0) {
+            capturePosthogEvent("api_reference_multiple_descriptions", {
+                name,
+                slug,
+                anchorIdParts,
+                count: descriptions.length,
+                descriptions,
+            });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [descriptions]);
+
     return (
         <div
             ref={ref}
@@ -113,7 +129,7 @@ export const EndpointParameterContent: FC<PropsWithChildren<EndpointParameter.Co
                     {availability != null && <EndpointAvailabilityTag availability={availability} minimal={true} />}
                 </span>
             </FernAnchor>
-            <Markdown mdx={compact([description, ...additionalDescriptions])} className="!t-muted" size="sm" />
+            <Markdown mdx={descriptions[0]} className="!t-muted" size="sm" />
             {children}
         </div>
     );

diff --git a/packages/ui/app/src/api-reference/types/discriminated-union/DiscriminatedUnionVariant.tsx b/packages/ui/app/src/api-reference/types/discriminated-union/DiscriminatedUnionVariant.tsx
@@ -4,7 +4,8 @@ import type * as FernNavigation from "@fern-api/fdr-sdk/navigation";
 import titleCase from "@fern-api/ui-core-utils/titleCase";
 import cn from "clsx";
 import { compact } from "lodash-es";
-import { useCallback, useMemo } from "react";
+import { useCallback, useEffect, useMemo } from "react";
+import { capturePosthogEvent } from "../../../analytics/posthog";
 import { Markdown } from "../../../mdx/Markdown";
 import { EndpointAvailabilityTag } from "../../endpoints/EndpointAvailabilityTag";
 import {
@@ -33,7 +34,7 @@ export const DiscriminatedUnionVariant: React.FC<DiscriminatedUnionVariant.Props
 }) => {
     const { isRootTypeDefinition } = useTypeDefinitionContext();
 
-    const [shape, descriptions] = useMemo((): [ApiDefinition.TypeShape.Object_, FernDocs.MarkdownText[]] => {
+    const [shape, additionalDescriptions] = useMemo((): [ApiDefinition.TypeShape.Object_, FernDocs.MarkdownText[]] => {
         const unwrapped = ApiDefinition.unwrapDiscriminatedUnionVariant({ discriminant }, unionVariant, types);
         return [
             {
@@ -62,6 +63,22 @@ export const DiscriminatedUnionVariant: React.FC<DiscriminatedUnionVariant.Props
         [contextValue, discriminant, unionVariant.discriminantValue],
     );
 
+    const descriptions = compact([unionVariant.description, ...additionalDescriptions]);
+
+    useEffect(() => {
+        if (descriptions.length > 0) {
+            capturePosthogEvent("api_reference_multiple_descriptions", {
+                slug,
+                anchorIdParts,
+                discriminant,
+                discriminantValue: unionVariant.discriminantValue,
+                count: descriptions.length,
+                descriptions,
+            });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [descriptions]);
+
     return (
         <div
             className={cn("flex flex-col py-3 gap-2", {
@@ -75,7 +92,7 @@ export const DiscriminatedUnionVariant: React.FC<DiscriminatedUnionVariant.Props
                 <EndpointAvailabilityTag availability={unionVariant.availability} minimal={true} />
             )}
             <div className="flex flex-col">
-                <Markdown mdx={compact([unionVariant.description, ...descriptions])} size="sm" />
+                <Markdown mdx={descriptions[0]} size="sm" />
                 <TypeDefinitionContext.Provider value={newContextValue}>
                     <InternalTypeDefinition
                         shape={shape}

diff --git a/packages/ui/app/src/api-reference/types/object/ObjectProperty.tsx b/packages/ui/app/src/api-reference/types/object/ObjectProperty.tsx
@@ -2,7 +2,8 @@ import * as ApiDefinition from "@fern-api/fdr-sdk/api-definition";
 import * as FernNavigation from "@fern-api/fdr-sdk/navigation";
 import cn from "clsx";
 import { compact } from "lodash-es";
-import { forwardRef, memo, useCallback, useMemo, useRef, useState } from "react";
+import { forwardRef, memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { capturePosthogEvent } from "../../../analytics/posthog";
 import { useIsApiReferencePaginated, useRouteListener } from "../../../atoms";
 import { FernAnchor } from "../../../components/FernAnchor";
 import { FernErrorBoundary } from "../../../components/FernErrorBoundary";
@@ -106,6 +107,19 @@ const UnmemoizedObjectPropertyInternal = forwardRef<HTMLDivElement, ObjectProper
         return compact([property.description, ...unwrapped.descriptions]);
     }, [property.description, property.valueShape, types]);
 
+    useEffect(() => {
+        if (descriptions.length > 0) {
+            capturePosthogEvent("api_reference_multiple_descriptions", {
+                name: property.key,
+                slug,
+                anchorIdParts,
+                count: descriptions.length,
+                descriptions,
+            });
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [descriptions]);
+
     return (
         <div
             ref={ref}
@@ -144,7 +158,7 @@ const UnmemoizedObjectPropertyInternal = forwardRef<HTMLDivElement, ObjectProper
                     </TypeDefinitionContext.Provider>
                 </FernErrorBoundary>
             )}
-            <Markdown mdx={descriptions} size="sm" />
+            <Markdown mdx={descriptions[0]} size="sm" />
             {hasInternalTypeReference(property.valueShape, types) && !hasInlineEnum(property.valueShape, types) && (
                 <FernErrorBoundary component="ObjectProperty">
                     <TypeDefinitionContext.Provider value={newContextValue}>

diff --git a/packages/ui/app/src/mdx/Markdown.tsx b/packages/ui/app/src/mdx/Markdown.tsx
@@ -7,7 +7,8 @@ export declare namespace Markdown {
     export interface Props {
         title?: ReactNode;
 
-        mdx: FernDocs.MarkdownText | FernDocs.MarkdownText[] | undefined;
+        // mdx: FernDocs.MarkdownText | FernDocs.MarkdownText[] | undefined;
+        mdx: FernDocs.MarkdownText | undefined;
         className?: string;
         size?: "xs" | "sm" | "lg";
 
@@ -20,7 +21,10 @@ export declare namespace Markdown {
 
 export const Markdown = memo<Markdown.Props>(({ title, mdx, className, size, fallback }) => {
     // If the MDX is empty, return null
-    if (!fallback && (mdx == null || (typeof mdx === "string" && mdx.trim().length === 0))) {
+    if (
+        !fallback &&
+        (mdx == null || (typeof mdx === "string" ? mdx.trim().length === 0 : mdx.code.trim().length === 0))
+    ) {
         return null;
     }