Merge pull request #481 from nhost/fix/docgen-tags

.gitignore

@@ -53,5 +53,4 @@ todo.md
 
 # TypeDoc output
 
-**/__tsdoc__
-**/__tsdoc__/*
+.docgen

docs/docs/reference/docgen/nextjs/content/use-auth-loading.mdx

@@ -10,8 +10,8 @@ description: No description provided.
 # `useAuthLoading()`
 
 :::caution Deprecated
-When using both `useAuthLoading` and `useAuthenticated` together, their initial state will change
-three times:
+When using both `useAuthLoading` and `useAuthenticated` together, their initial state
+will change three times:
 
 `(true, false)` -> `(false, false)` -> `(false, true)`
 

docs/docs/reference/docgen/react/content/use-auth-loading.mdx

@@ -10,8 +10,8 @@ description: No description provided.
 # `useAuthLoading()`
 
 :::caution Deprecated
-When using both `useAuthLoading` and `useAuthenticated` together, their initial state will change
-three times:
+When using both `useAuthLoading` and `useAuthenticated` together, their initial state
+will change three times:
 
 `(true, false)` -> `(false, false)` -> `(false, true)`
 

packages/docgen/README.md

@@ -25,7 +25,7 @@ DocGen is an opinionated tool that works the best with Nhost's own codebase.
 
 ```json
 {
-  "path": "./__tsdoc__/auth.json",
+  "path": "./.docgen/auth.json",
   "output": "../../docs/docs/reference/docgen/javascript/auth",
   "root": "reference/docgen/javascript/auth",
   "title": "Auth",

packages/docgen/src/fragments/CommentFragment.ts

@@ -1,3 +1,4 @@
+import { removeLinksFromText } from '../helpers'
 import { Comment } from '../types'
 import { CommentTagFragment } from './CommentTagFragment'
 
@@ -29,11 +30,13 @@ ${
   tags
     ? tags
         .filter(({ tag }) => !excludedTags.includes(tag))
-        .concat(returns ? { tag: 'returns', text: returns } : { tag: ``, text: `` })
+        .concat(
+          returns ? { tag: 'returns', text: removeLinksFromText(returns) } : { tag: ``, text: `` }
+        )
         .map(CommentTagFragment)
         .join('\n\n')
     : returns
-    ? CommentTagFragment({ tag: 'returns', text: returns })
+    ? CommentTagFragment({ tag: 'returns', text: removeLinksFromText(returns) })
     : ``
 }`
 

packages/docgen/src/fragments/CommentTagFragment.ts

@@ -1,3 +1,4 @@
+import { removeLinksFromText } from '../helpers'
 import { CommentTag } from '../types'
 
 /**
@@ -12,8 +13,8 @@ export const CommentTagFragment = ({ tag, text }: CommentTag) =>
 ${
   text
     ? tag && tag === 'default'
-      ? `\`${text.replace(/(^\n|\n$)/gi, ``).replace(/'/gi, '"')}\``
-      : `${text.replace(/(^\n|\n$)/gi, ``)}`
+      ? `\`${removeLinksFromText(text.replace(/(^\n|\n$)/gi, ``).replace(/'/gi, '"'))}\``
+      : `${removeLinksFromText(text.replace(/(^\n|\n$)/gi, ``))}`
     : ``
 }`
 

packages/docgen/src/fragments/DeprecationNoteFragment.ts

@@ -1,3 +1,4 @@
+import { removeLinksFromText } from '../helpers'
 import { CommentTag } from '../types'
 
 /**
@@ -11,7 +12,7 @@ export const DeprecationNoteFragment = (
   tag: CommentTag,
   defaultMessage: string = 'No description provided.'
 ) => `:::caution Deprecated
-${tag.text.replace(/(^\n|\n$)/gi, ``) || defaultMessage}
+${removeLinksFromText(tag.text.replace(/(^\n|\n$)/gi, ``)) || defaultMessage}
 :::`
 
 export default DeprecationNoteFragment

packages/docgen/src/fragments/FunctionFragment.ts

@@ -1,4 +1,8 @@
-import { getExamplesFromSignature, getNestedParametersFromParameter } from '../helpers'
+import {
+  getExamplesFromSignature,
+  getNestedParametersFromParameter,
+  removeLinksFromText
+} from '../helpers'
 import { Signature } from '../types'
 import CommentFragment from './CommentFragment'
 import CommentTagFragment from './CommentTagFragment'
@@ -110,9 +114,9 @@ ${
   signature.comment &&
   signature.comment.tags &&
   signature.comment.tags.some(({ tag }) => tag === 'remarks')
-    ? `${isConstructor || numberOfOverloads > 1 ? '### Notes' : '## Notes'}\n${
+    ? `${isConstructor || numberOfOverloads > 1 ? '### Notes' : '## Notes'}\n${removeLinksFromText(
         signature.comment.tags.find(({ tag }) => tag === 'remarks')?.text
-      }`
+      )}`
     : ``
 }
 

packages/docgen/src/fragments/ParameterTableFragment.ts

@@ -1,4 +1,4 @@
-import { GetLabelForTypeOptions, getLabelForType } from '../helpers'
+import { GetLabelForTypeOptions, getLabelForType, removeLinksFromText } from '../helpers'
 import { Parameter } from '../types'
 import FunctionSignatureTypeFragment from './FunctionSignatureTypeFragment'
 
@@ -32,7 +32,9 @@ ${parameters
         : parameter.name
     }</span> ${
       deprecationNote
-        ? `<span className="deprecation-sign" title="${deprecationNote.text}">⚠️</span>`
+        ? `<span className="deprecation-sign" title="${removeLinksFromText(
+            deprecationNote.text
+          )}">⚠️</span>`
         : ''
     } | ${
       // function signatures behave slightly differently than other types
@@ -42,7 +44,7 @@ ${parameters
         ? getLabelForType(parameter.type, labelOptions).replace(/\|/gi, '\\|')
         : getLabelForType(parameter.type, labelOptions)
     } | ${parameter.flags.isOptional ? `` : '✔️'} | ${
-      parameter.comment?.shortText?.replace(/\n/gi, ' ') || ''
+      removeLinksFromText(parameter.comment?.shortText?.replace(/\n/gi, ' ')) || ''
     }|`
   })
   .join('\n')}

packages/docgen/src/generators/generateClasses.ts

@@ -24,7 +24,7 @@ export async function generateClasses(parsedContent: Array<ClassSignature>, outp
     index: string
     subPages: Array<Signature>
     slug?: string
-  }> = parsedContent
+  }> = (parsedContent || [])
     .filter((document) => document.kindString === 'Class')
     .map((props: ClassSignature) => {
       const alias = props.comment?.tags?.find(({ tag }) => tag === 'alias')?.text?.toLowerCase()

packages/docgen/src/generators/generateFunctions.ts

@@ -35,7 +35,7 @@ export async function generateFunctions(
   const finalOutputPath = `${outputPath}/content`
   const { baseSlug, verbose } = snapshot(appState)
   const { FunctionTemplate } = await import('../templates')
-  const functions: Array<{ name: string; content: string }> = parsedContent
+  const functions: Array<{ name: string; content: string }> = (parsedContent || [])
     .filter((document) => ['Function', 'Method'].includes(document.kindString))
     .map((props: Signature) => ({
       name: props.name,

packages/docgen/src/generators/generateTypes.ts

@@ -27,7 +27,7 @@ export async function generateTypes(
   const { TypeTemplate } = await import('../templates')
   const finalOutputPath = sameLevel ? outputPath : `${outputPath}/types`
 
-  const types: Array<{ name: string; content: string }> = parsedContent
+  const types: Array<{ name: string; content: string }> = (parsedContent || [])
     .filter((document) => ['Type alias', 'Interface'].includes(document.kindString))
     .map((props) => ({
       name: props.name,

packages/docgen/src/helpers/index.ts

@@ -8,3 +8,5 @@ export * from './getModuleContentMap'
 export { default as getModuleContentMap } from './getModuleContentMap'
 export * from './getNestedParametersFromParameter'
 export { default as getNestedParametersFromParameter } from './getNestedParametersFromParameter'
+export * from './removeLinksFromText'
+export { default as removeLinksFromText } from './removeLinksFromText'

packages/docgen/src/helpers/removeLinksFromText.test.ts

@@ -0,0 +1,24 @@
+import removeLinksFromText from './removeLinksFromText'
+
+test('should return an empty string if text is undefined', () => {
+  expect(removeLinksFromText()).toBe('')
+  expect(removeLinksFromText(undefined)).toBe('')
+})
+
+test('comment should contain only the text of a TSDoc link', () => {
+  expect(removeLinksFromText(`This comment has links to {@link removeLinksFromText}.`)).toBe(
+    `This comment has links to removeLinksFromText.`
+  )
+
+  expect(removeLinksFromText(`{@link https://custom-url.example.com?query=test+text#L62}`)).toBe(
+    `https://custom-url.example.com?query=test+text#L62`
+  )
+})
+
+test('comment should contain only the texts of TSDoc links', () => {
+  expect(
+    removeLinksFromText(
+      `This comment has links to {@link removeLinksFromText} and some other {@link customFunction}.`
+    )
+  ).toBe(`This comment has links to removeLinksFromText and some other customFunction.`)
+})

packages/docgen/src/helpers/removeLinksFromText.ts

@@ -0,0 +1,15 @@
+/**
+ * Replaces links in a text with the text of the link.
+ *
+ * @param text - Text to remove links from
+ * @returns Text without links
+ */
+export function removeLinksFromText(text?: string) {
+  if (!text) {
+    return ''
+  }
+
+  return text.replace(/\{@link ?(\w+|\S+)\}/g, '$1')
+}
+
+export default removeLinksFromText

packages/docgen/src/index.ts

@@ -174,7 +174,9 @@ async function parser() {
         })
       )
     } else {
-      appState.contentReferences = getModuleContentMap(groups)
+      if (groups) {
+        appState.contentReferences = getModuleContentMap(groups)
+      }
 
       await generateModuleDocumentation(parsedContent, output)
     }

packages/docgen/src/templates/ClassTemplate.ts

@@ -1,6 +1,7 @@
 import { format } from 'prettier'
 
 import { CommentFragment, DeprecationNoteFragment, FunctionFragment } from '../fragments'
+import { removeLinksFromText } from '../helpers'
 import { ClassSignature, Signature } from '../types'
 
 /**
@@ -23,7 +24,9 @@ export const ClassTemplate = (
 # ⚠️ AUTO-GENERATED CONTENT. DO NOT EDIT THIS FILE DIRECTLY! ⚠️
 title: ${name}
 sidebar_label: ${alias || name}
-description: ${comment?.shortText?.replace(/\n/gi, ' ') || 'No description provided.'}
+description: ${
+    removeLinksFromText(comment?.shortText?.replace(/\n/gi, ' ')) || 'No description provided.'
+  }
 ${deprecationTag ? 'sidebar_class_name: deprecated' : ``}
 ${slug ? `slug: ${slug}` : ``}
 ---`.replace(/\n\n/gi, '\n')

packages/docgen/src/templates/FunctionTemplate.ts

@@ -1,6 +1,7 @@
 import { format } from 'prettier'
 
 import { FunctionFragment, FunctionFragmentOptions } from '../fragments'
+import { removeLinksFromText } from '../helpers'
 import { Signature } from '../types'
 
 /**
@@ -32,7 +33,8 @@ ${allChildrenDeprecated ? 'sidebar_class_name: deprecated' : ''}
 ${
   signatures && signatures.length > 0
     ? `description: ${
-        signatures[0].comment?.shortText?.replace(/\n/gi, ' ') || 'No description provided.'
+        removeLinksFromText(signatures[0].comment?.shortText?.replace(/\n/gi, ' ')) ||
+        'No description provided.'
       }`
     : 'description: No description provided.'
 }

packages/hasura-auth-js/auth.docgen.json

@@ -1,6 +1,6 @@
 {
   "title": "Auth",
-  "path": "./__tsdoc__/auth.json",
+  "path": "./.docgen/auth.json",
   "output": "../../docs/docs/reference/docgen/javascript/auth",
   "root": "reference/docgen/javascript/auth",
   "slug": "/reference/javascript/auth",

packages/hasura-auth-js/auth.typedoc.json

@@ -4,7 +4,7 @@
   "entryPoints": ["."],
   "exclude": "*.(spec|test).tsx?",
   "sort": ["source-order"],
-  "json": "./__tsdoc__/auth.json",
+  "json": "./.docgen/auth.json",
   "name": "Auth",
   "readme": "none",
   "githubPages": false,

packages/hasura-storage-js/storage.docgen.json

@@ -1,6 +1,6 @@
 {
   "title": "Storage",
-  "path": "./__tsdoc__/storage.json",
+  "path": "./.docgen/storage.json",
   "output": "../../docs/docs/reference/docgen/javascript/storage",
   "root": "reference/docgen/javascript/storage",
   "slug": "/reference/javascript/storage",

packages/hasura-storage-js/storage.typedoc.json

@@ -4,7 +4,7 @@
   "entryPoints": ["."],
   "exclude": "*.(spec|test).tsx?",
   "sort": ["source-order"],
-  "json": "./__tsdoc__/storage.json",
+  "json": "./.docgen/storage.json",
   "name": "Storage",
   "readme": "none",
   "githubPages": false,

packages/nextjs/nextjs.docgen.json

@@ -1,6 +1,6 @@
 {
   "title": "Next.js",
-  "path": "./__tsdoc__/nextjs.json",
+  "path": "./.docgen/nextjs.json",
   "output": "../../docs/docs/reference/docgen/nextjs",
   "root": "reference/docgen/nextjs",
   "slug": "/reference/nextjs",

packages/nextjs/nextjs.typedoc.json

@@ -4,7 +4,7 @@
   "entryPoints": ["."],
   "exclude": "*.(spec|test).tsx?",
   "sort": ["source-order"],
-  "json": "./__tsdoc__/nextjs.json",
+  "json": "./.docgen/nextjs.json",
   "name": "Next.js",
   "readme": "none",
   "githubPages": false,

packages/nhost-js/nhost-js.docgen.json

@@ -1,6 +1,6 @@
 {
   "title": "Nhost JS",
-  "path": "./__tsdoc__/nhost-js.json",
+  "path": "./.docgen/nhost-js.json",
   "output": "../../docs/docs/reference/docgen/javascript/nhost-js",
   "root": "reference/docgen/javascript/nhost-js",
   "slug": "/reference/javascript/nhost-js",

packages/nhost-js/nhost-js.typedoc.json

@@ -4,7 +4,7 @@
   "entryPoints": ["."],
   "exclude": "*.(spec|test).tsx?",
   "sort": ["source-order"],
-  "json": "./__tsdoc__/nhost-js.json",
+  "json": "./.docgen/nhost-js.json",
   "name": "Nhost JS",
   "readme": "none",
   "githubPages": false,

packages/react/react.docgen.json

@@ -1,6 +1,6 @@
 {
   "title": "React",
-  "path": "./__tsdoc__/react.json",
+  "path": "./.docgen/react.json",
   "output": "../../docs/docs/reference/docgen/react",
   "root": "reference/docgen/react",
   "slug": "/reference/react",

packages/react/react.typedoc.json

@@ -4,7 +4,7 @@
   "entryPoints": ["."],
   "exclude": "*.(spec|test).tsx?",
   "sort": ["source-order"],
-  "json": "./__tsdoc__/react.json",
+  "json": "./.docgen/react.json",
   "name": "React",
   "readme": "none",
   "githubPages": false,

packages/react/src/hooks/authentication.ts

@@ -368,7 +368,7 @@ export const useSignInAnonymous = () => {
 
 /**
  * Hook that returns OAuth provider URLs
- * 
+ *
  * @example
  * ```js
  * const providerLink = useProviderLink();
@@ -388,8 +388,8 @@ export const useSignInAnonymous = () => {
  *     </div>
  *   );
  * };
-```
-*/
+ * ```
+ */
 export const useProviderLink = (options?: ProviderOptions) => {
   const nhost = useContext(NhostReactContext)
 

packages/react/src/hooks/common.ts

@@ -49,8 +49,8 @@ export const useNhostBackendUrl = () => {
 
 /**
  * @deprecated
- * When using both `useAuthLoading` and `useAuthenticated` together, their initial state will change
- * three times:
+ * When using both `useAuthLoading` and `useAuthenticated` together, their initial state
+ * will change three times:
  *
  * `(true, false)` -> `(false, false)` -> `(false, true)`
  *