docs: remove jsdoc @links from generated documentation (#1261)

EMP-1782
empathyco · Aug 23, 2023 · 9082fb2 · 9082fb2
1 parent 0d3d088
commit 9082fb2
Show file tree

Hide file tree

Showing 42 changed files with 89 additions and 74 deletions.
diff --git a/packages/x-components/build/docgen/templates/docgen-component.template.js b/packages/x-components/build/docgen/templates/docgen-component.template.js
@@ -1,13 +1,17 @@
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { removeLinks } = require('../utils');
+
 function createComponentTemplate(renderedUsage, doc) {
   const { displayName, description, docsBlocks } = doc;
   const title = kebabToPascalCase(displayName);
+  const modifiedDescription = removeLinks(description);
   return `
   ---
   title: ${title}
   ---
   # ${title}
 
-  ${description || ''}
+  ${modifiedDescription || ''}
 
   ${renderedUsage.props}
   ${renderedUsage.methods}

diff --git a/packages/x-components/build/docgen/templates/docgen-props.template.js b/packages/x-components/build/docgen/templates/docgen-props.template.js
@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
-const { cleanMarkdown } = require('../utils');
+const { cleanMarkdown, removeLinks } = require('../utils');
 
 /**
  * Function to overwrite props template on vue-docgen.
@@ -33,7 +33,7 @@ function toPropsMarkdownTable({ name = '', type = {}, defaultValue = {}, descrip
   const value = defaultValue.value ? defaultValue.value : '';
 
   return `| <code>${cleanMarkdown(name)}</code> | ${cleanMarkdown(
-    description
+    removeLinks(description)
   )} | <code>${cleanMarkdown(typeName)}</code> | <code>${cleanMarkdown(value)}</code> |`;
 }
 

diff --git a/packages/x-components/build/docgen/utils.js b/packages/x-components/build/docgen/utils.js
@@ -12,6 +12,18 @@ function cleanMarkdown(input) {
   return input.replace(/\r?\n/g, '<br />').replace(/\|/g, '\\|');
 }
 
+/**
+ * Replaces all the `{@link Component}` appearances to not be shown on generated docs.
+ *
+ * @param input - Input to be cleaned.
+ * @returns String cleaned markdown compatible string.
+ *
+ * @internal
+ */
+function removeLinks(input) {
+  return input.replace(/{@link /g, '').replace(/}/g, '');
+}
+
 const COMPONENTS_DOC_FOLDER = 'API-reference/components';
 
 /**
@@ -60,6 +72,7 @@ function generateDestination(folder, regex, file) {
 
 module.exports = {
   cleanMarkdown,
+  removeLinks,
   getDocumentFileDestination,
   COMPONENTS_DOC_FOLDER
 };
diff --git a/packages/x-components/src/components/animations/staggering-transition-group.vue b/packages/x-components/src/components/animations/staggering-transition-group.vue
@@ -432,7 +432,7 @@
   }
 
   /**
-   * Vue's VNode {@link https://vuejs.org/v2/api/#transition | transition} data props and events.
+   * Vue's VNode {@link https://vuejs.org/v2/api/#transition} data props and events.
    */
   interface TransitionData {
     name?: string;

diff --git a/packages/x-components/src/components/base-event-button.vue b/packages/x-components/src/components/base-event-button.vue
@@ -12,7 +12,7 @@
 
   /**
    * Component to be reused that renders a `<button>` with the logic of emitting events to the bus
-   * on click. The events are passed as an object to prop {@link XEventsTypes | events}.
+   * on click. The events are passed as an object to prop {@link XEventsTypes}.
    * The keys are the event name and the values are the payload of each event. All events are
    * emitted with its respective payload. If any event doesn't need payload a `undefined` must be
    * passed as value.

diff --git a/packages/x-components/src/components/base-grid.vue b/packages/x-components/src/components/base-grid.vue
@@ -98,7 +98,7 @@
     public injectedListItems!: ListItem[];
 
     /**
-     * Emits the {@link XEventsTypes.RenderedColumnsNumberChanged | RenderedColumnsNumberChanged}
+     * Emits the {@link XEventsTypes.RenderedColumnsNumberChanged}
      * event whenever the number of columns rendered inside the grid changes.
      *
      * @internal

diff --git a/packages/x-components/src/components/base-keyboard-navigation.vue b/packages/x-components/src/components/base-keyboard-navigation.vue
@@ -35,7 +35,7 @@
   @Component
   export default class BaseKeyboardNavigation extends Vue {
     /**
-     * An array of {@link TakeNavigationControl | navigation hijacker} objects defining when to
+     * An array of {@link TakeNavigationControl} objects defining when to
      * take control of the keyboard navigation.
      */
     @Prop({
@@ -53,7 +53,7 @@
     protected eventsForDirectionLimit!: Partial<EventsForDirectionLimit>;
 
     /**
-     * The {@link SpatialNavigation | navigation service} to use.
+     * The {@link SpatialNavigation} service to use.
      */
     protected navigationService!: SpatialNavigation;
 

diff --git a/packages/x-components/src/components/column-picker/base-column-picker-dropdown.vue b/packages/x-components/src/components/column-picker/base-column-picker-dropdown.vue
@@ -38,10 +38,10 @@
   import ColumnPickerMixin from './column-picker.mixin';
 
   /**
-   * Column picker dropdown component renders {@link BaseDropdown | dropdown} component which
+   * Column picker dropdown component renders {@link BaseDropdown} component which
    * options are the different columns you can set for a grid.
    *
-   * It emits {@link XEventsTypes.UserClickedColumnPicker | UserClickedColumnPicker} on dropdown
+   * It emits {@link XEventsTypes.UserClickedColumnPicker} on dropdown
    * input.
    *
    * @remarks It extends {@link ColumnPickerMixin}.
@@ -61,8 +61,8 @@
     public animation?: string | typeof Vue;
 
     /**
-     * Emits a {@link XEventsTypes.UserClickedColumnPicker | UserClickedColumnPicker} and
-     * {@link XEventsTypes.ColumnsNumberProvided | ColumnsNumberProvided} events.
+     * Emits a {@link XEventsTypes.UserClickedColumnPicker} and
+     * {@link XEventsTypes.ColumnsNumberProvided} events.
      *
      * @param column - Column number payload.
      */

diff --git a/packages/x-components/src/components/modals/base-events-modal-close.vue b/packages/x-components/src/components/modals/base-events-modal-close.vue
@@ -18,8 +18,7 @@
   import BaseEventButton from '../base-event-button.vue';
 
   /**
-   * Component contains an event button that emits {@link
-   * XEventsTypes.UserClickedCloseEventsModal}
+   * Component contains an event button that emits {@link XEventsTypes.UserClickedCloseEventsModal}
    * when clicked. It has a default slot to customize its contents.
    *
    * @public

diff --git a/packages/x-components/src/components/modals/base-events-modal.vue b/packages/x-components/src/components/modals/base-events-modal.vue
@@ -22,8 +22,8 @@
   /**
    * Component containing a modal that emits a {@link XEventsTypes.UserClickedCloseEventsModal} when
    * clicking outside the content rendered in the default slot and can receive, through the
-   * eventsToCloseModal prop, a list of {@link XEvent | xEvents} to listen to in order to close
-   * also the modal, eventsToOpenModal prop,  another list of {@link XEvent | xEvents} to customize
+   * eventsToCloseModal prop, a list of {@link XEvent} to listen to in order to close
+   * also the modal, eventsToOpenModal prop,  another list of {@link XEvent} to customize
    * the events to listen to open the modal and a prop, displayOverlay, to display an
    * overlay over the rest of the html. The default slot offers the possibility to customize the
    * modal content.
@@ -40,13 +40,13 @@
     @Prop()
     public animation?: Vue | string;
     /**
-     * Array of {@link XEvent | xEvents} to listen to open the modal.
+     * Array of {@link XEvent} to listen to open the modal.
      */
     @Prop({ default: (): XEvent[] => ['UserClickedOpenEventsModal'] })
     public eventsToOpenModal!: XEvent[];
 
     /**
-     * Array of {@link XEvent | xEvents} to listen to close the modal.
+     * Array of {@link XEvent} to listen to close the modal.
      */
     @Prop({
       default: (): XEvent[] => ['UserClickedCloseEventsModal', 'UserClickedOutOfEventsModal']

diff --git a/packages/x-components/src/components/result/base-result-add-to-cart.vue b/packages/x-components/src/components/result/base-result-add-to-cart.vue
@@ -26,7 +26,7 @@
     components: { BaseEventButton },
     props: {
       /**
-       * (Required) The {@link @empathyco/x-types#Result | result} information.
+       * (Required) The {@link @empathyco/x-types#Result} information.
        *
        * @public
        */

diff --git a/packages/x-components/src/components/result/base-result-current-price.vue b/packages/x-components/src/components/result/base-result-current-price.vue
@@ -17,7 +17,7 @@
   import BaseCurrency from '../currency/base-currency.vue';
 
   /**
-   * Component that renders the {@link @empathyco/x-types#Result | result} current price
+   * Component that renders the {@link @empathyco/x-types#Result} current price
    * that may or may not be on sale.
    *
    * @public
@@ -26,7 +26,7 @@
     components: { BaseCurrency },
     props: {
       /**
-       * (Required) The {@link @empathyco/x-types#Result | result} information.
+       * (Required) The {@link @empathyco/x-types#Result} information.
        *
        * @public
        */

diff --git a/packages/x-components/src/components/result/base-result-image.vue b/packages/x-components/src/components/result/base-result-image.vue
@@ -56,7 +56,7 @@
     },
     props: {
       /**
-       * (Required) The {@link @empathyco/x-types#Result | result} information.
+       * (Required) The {@link @empathyco/x-types#Result} information.
        *
        * @public
        */

diff --git a/packages/x-components/src/components/result/base-result-link.vue b/packages/x-components/src/components/result/base-result-link.vue
@@ -37,7 +37,7 @@
   export default defineComponent({
     props: {
       /**
-       * (Required) The {@link @empathyco/x-types#Result | result} information.
+       * (Required) The {@link @empathyco/x-types#Result} information.
        *
        * @public
        */

diff --git a/packages/x-components/src/components/result/base-result-previous-price.vue b/packages/x-components/src/components/result/base-result-previous-price.vue
@@ -20,15 +20,15 @@
   import BaseCurrency from '../currency/base-currency.vue';
 
   /**
-   * Component that renders the {@link @empathyco/x-types#Result | result} previous price.
+   * Component that renders the {@link @empathyco/x-types#Result} previous price.
    *
    * @public
    */
   export default defineComponent({
     components: { BaseCurrency },
     props: {
       /**
-       * (Required) The {@link @empathyco/x-types#Result | result} information.
+       * (Required) The {@link @empathyco/x-types#Result} information.
        *
        * @public
        */

diff --git a/packages/x-components/src/components/result/base-result-rating.vue b/packages/x-components/src/components/result/base-result-rating.vue
@@ -48,7 +48,7 @@
     },
     props: {
       /**
-       * The {@link @empathyco/x-types#Result | Result} to render its rating.
+       * The {@link @empathyco/x-types#Result} to render its rating.
        *
        * @public
        */
@@ -71,7 +71,7 @@
 
       /**
        * Emits the `UserClickedAResultRating` event when user clicks this component, with the
-       * {@link @empathyco/x-types#Result | Result} as payload.
+       * {@link @empathyco/x-types#Result} as payload.
        *
        * @internal
        */

diff --git a/packages/x-components/src/components/sliding-panel.vue b/packages/x-components/src/components/sliding-panel.vue
@@ -181,7 +181,7 @@
     }
 
     /**
-     * Debounced version of the {@link SlidingPanel.updateScrollPosition | updateScrollPosition}
+     * Debounced version of the {@link SlidingPanel.updateScrollPosition}
      * method.
      *
      * @internal

diff --git a/packages/x-components/src/components/suggestions/base-suggestion.vue b/packages/x-components/src/components/suggestions/base-suggestion.vue
@@ -25,7 +25,7 @@
 
   /**
    * Renders a button with a default slot. It receives a query, which should be the query of the
-   * module using this component, a suggestion, the {@link XEvent | XEvents} that will be emitted
+   * module using this component, a suggestion, the {@link XEvent} that will be emitted
    * on click with a given feature.
    *
    * The default slot receives the suggestion and the matched query has props.
@@ -66,7 +66,7 @@
       },
 
       /**
-       * The {@link XEvent | XEvents} that will be emitted when selecting a suggestion.
+       * The {@link XEvent} that will be emitted when selecting a suggestion.
        *
        * @public
        */
@@ -112,7 +112,7 @@
        * UserClickedAFilter: suggestion.facets[0].filters[0]
        * Merges the events defined in the suggestionSelectedEvents prop and also emits them
        *
-       * @returns The {@link XEvent | XEvents} to emit.
+       * @returns The {@link XEvent} to emit.
        * @public
        */
       const events = computed<Partial<XEventsTypes>>(() => {

diff --git a/packages/x-components/src/x-modules/empathize/components/empathize.vue b/packages/x-components/src/x-modules/empathize/components/empathize.vue
@@ -48,15 +48,15 @@
     protected animation!: Vue;
 
     /**
-     * Array of {@link XEvent | xEvents} to open the empathize.
+     * Array of {@link XEvent} to open the empathize.
      *
      * @public
      */
     @Prop({ default: () => ['UserFocusedSearchBox', 'UserIsTypingAQuery', 'UserClickedSearchBox'] })
     protected eventsToOpenEmpathize!: XEvent[];
 
     /**
-     * Array of {@link XEvent | xEvents} to close the empathize.
+     * Array of {@link XEvent} to close the empathize.
      *
      * @public
      */
@@ -92,7 +92,7 @@
     protected hasContent = false;
 
     /**
-     * The Vue lifecycle hook {@link https://vuex.vuejs.org/guide/state.html | updated} is called
+     * The Vue lifecycle hook [https://vuex.vuejs.org/guide/state.html](updated) is called
      * after a data change causes the virtual DOM to be re-rendered and patched. Using it to detect
      * if the default slot content has been replaced.
      *
@@ -137,11 +137,11 @@
 
     /**
      * Changes the state of {@link Empathize.isOpen} assigning to it the value of `newOpenState`
-     * parameter. Also emits the {@link XEvent | XEvents} `EmpathizeOpened` or `EmpathizeClosed` if
+     * parameter. Also emits the {@link XEvent} `EmpathizeOpened` or `EmpathizeClosed` if
      * the state really changes.
      *
      * @param newOpenState - The new state to assign to {@link Empathize.isOpen}.
-     * @param metadata - The {@link WireMetadata} to emit the {@link XEvent | XEvents}. If it is
+     * @param metadata - The {@link WireMetadata} to emit the {@link XEvent}. If it is
      * undefined, this component is used as source of info for the metadata.
      *
      * @internal

diff --git a/packages/x-components/src/x-modules/facets/components/facets/facets-provider.vue b/packages/x-components/src/x-modules/facets/components/facets/facets-provider.vue
@@ -34,7 +34,7 @@
 
     /**
      * The facets to provide to the `Facets X-Module` state. They have to include the
-     * {@link @empathyco/x-types#Filter | filters}.
+     * {@link @empathyco/x-types#Filter}.
      *
      * @internal
      */
@@ -123,7 +123,7 @@
 
 This component allows to provide facets by prop, to add them to the state of the `Facets X-Module`.
 These facets will be added to the `Facets X-Module` state together with the facets emitted by the
-`Search X-Module` through the {@link SearchXEvents.FacetsChanged} event.
+`Search X-Module` through the `SearchXEvents.FacetsChanged` event.
 
 ```vue
 <template>

diff --git a/packages/x-components/src/x-modules/facets/components/filters/all-filter.vue b/packages/x-components/src/x-modules/facets/components/filters/all-filter.vue
@@ -29,7 +29,7 @@
 
   /**
    * This component receives a required `facet` with
-   * {@link @empathyco/x-types#BooleanFilter | BooleanFilter} as prop and renders a button, which
+   * {@link @empathyco/x-types#BooleanFilter} as prop and renders a button, which
    * on clicked emits the {@link FacetsXEvents.UserClickedAllFilter} event. By default
    * the rendered button displays a message with the facet label but this content is customizable
    * through the default slot.

diff --git a/...ges/x-components/src/x-modules/facets/components/filters/editable-number-range-filter.vue b/...ges/x-components/src/x-modules/facets/components/filters/editable-number-range-filter.vue
@@ -201,7 +201,7 @@
     }
 
     /**
-     * Returns {@link @empathyco/x-types#RangeValue | RangeValue} with component min and max
+     * Returns {@link @empathyco/x-types#RangeValue} with component min and max
      * values.
      *
      * @returns Range value object with component values.

diff --git a/packages/x-components/src/x-modules/facets/components/filters/hierarchical-filter.vue b/packages/x-components/src/x-modules/facets/components/filters/hierarchical-filter.vue
@@ -106,7 +106,7 @@
     public clickEvents!: Partial<XEventsTypes>;
 
     /**
-     * The {@link XEventsTypes | events} to emit.
+     * The {@link XEventsTypes} to emit.
      *
      * @returns The events to emit when clicked.
      * @internal
@@ -134,7 +134,7 @@
 
     /**
      * Gets the child filter click events, converting the payload of the events that have a
-     * {@link @empathyco/x-types#HierarchicalFilter} as payload to the corresponding child filter.
+     * {@link HierarchicalFilter} as payload to the corresponding child filter.
      *
      * @param childFilter - The child filter.
      * @returns The events to emit when clicking a child.

diff --git a/packages/x-components/src/x-modules/facets/components/filters/number-range-filter.vue b/packages/x-components/src/x-modules/facets/components/filters/number-range-filter.vue
@@ -74,7 +74,7 @@
     public clickEvents?: Partial<XEventsTypes>;
 
     /**
-     * The {@link XEventsTypes | events} to emit.
+     * The {@link XEventsTypes} to emit.
      *
      * @returns The events to emit when clicked.
      * @internal

diff --git a/packages/x-components/src/x-modules/facets/components/filters/renderless-filter.vue b/packages/x-components/src/x-modules/facets/components/filters/renderless-filter.vue
@@ -9,7 +9,7 @@
 
   /**
    * Renders default slot content. It binds to the default slot a
-   * {@link @empathyco/x-types#BooleanFilter | BooleanFilter}, the {@link XEvent | XEvents}
+   * {@link @empathyco/x-types#BooleanFilter}, the {@link XEvent}
    * that will be emitted when clicking the content, the css classes and if the content should be
    * disabled.
    *