Explore auto-generating documentation for composables

[MisRob]

🌱 Are you new to the codebase? Welcome! Please see the contributing guidelines.

Summary

When the documentation website is built, there's logic that automatically extracts JSDoc comments from a KDS component and then inserts them into the component's documentation page.

For example, in the KImg component, the scaleType prop is documented with:

kolibri-design-system/lib/KImg/index.vue

Lines 124 to 132 in 0cbdf57

	/**
	* Specifies how an image should be scaled within the container.
	* Can be one of `'centerInside'`, `'contain'`, or `'fitXY'`.
	*/
	scaleType: {
	type: String,
	default: 'centerInside', // needs to be duplicated rather than using ScaleTypes.CENTER_INSIDE, otherwise it doesn't render correctly in the auto-generated Props documentation
	validator: isValidScaleType,
	},

When the website is built, the comment is automatically inserted into the "Props" section at the bottom of the KImg documentation page:

The same applies to components' "Events" and "Slots".

However, this only works for components, not for composables. For example, let’s have a look at useKShow composable. Even though useKShow's documentation page contains “Parameters” and “Returns”

These are not auto-generated from JSDoc, but written manually here

kolibri-design-system/docs/pages/usekshow.vue

Lines 109 to 117 in 0cbdf57

	<DocsPageSection title="Parameters" anchor="#parameters">
	<PropsTable :api="params" />
	</DocsPageSection>
	<DocsPageSection title="Returns" anchor="#returns">
	<p><span style="font-weight: bold">Type:</span> <code>boolean</code></p>
	<p><span style="font-weight: bold">Description:</span> Returns <code>true</code> after <code>shouldShow</code> becomes truthy and keeps returning <code>true</code> for the duration of <code>minVisibleTime</code> (even when <code>shouldShow</code> changes back to falsy meanwhile). After <code>minVisibleTime</code> elapses and when <code>shouldShow</code> is falsy already, it returns <code>false</code>.</p>
	</DocsPageSection>
	</DocsPageTemplate>

As we're moving toward using composables more widely in our products and Design System will soon have some new ones, it'd be valuable to have this bottom part of the documentation auto-generated for composables as well.

The goal of this issue is to research if and how we could achieve this and eventually prepare a proof of concept (PoC) implementation. Part of this issue is also exploring how the documentation website should roughly look like if a composable has more publicly exposed entities, such as more functions, some refs, some computed, etc.

Guidance

• See “Updating the library components documentation”, utils/extractApi.js, and DocsPageTemplate.vue to understand the current auto-generation system
• In the first iteration, it would be fine for the PoC to only generate “Parameters” and “Returns” sections right from the JSDoc comments here

  kolibri-design-system/lib/composables/useKShow/index.js

  Lines 26 to 52 in 0cbdf57

  	/**
  	* Guarantees that something will be displayed at least for a specified
  	* duration after an initial trigger
  	*
  	* This is typically used to prevent a jarring user experience when showing
  	* or hiding certain elements. For example, it can be used to ensure that a
  	* loader remains visible for a certain amount of time, even when the related
  	* data has already been loaded.
  	*
  	* @param {String, Number} key Each `show` function instance has to pass
  	* a key unique in the context of a whole page
  	* to this attribute
  	* @param {Boolean} shouldShow Accurate, real-time information on whether
  	* something should be shown. For example, it
  	* should be set to `false` for a loader immediately
  	* after related data have finished loading.
  	* @param {Number} minVisibleTime For how long should `show` return `true`
  	* after an initial trigger
  	*
  	* @returns {Boolean} Returns `true` after `shouldShow` becomes truthy
  	* and keeps returning `true` for the duration of
  	* `minVisibleTime` (even when `shouldShow` changes
  	* back to falsy meanwhile). After `minVisibleTime`
  	* elapses and when `shouldShow` is falsy already,
  	* it returns `false`.
  	*/
  	function show(key, shouldShow = false, minVisibleTime = 0) {

• However, the approach taken to prepare the PoC needs to be scalable since composables can contain much more than just one function - there could be more functions, computed, watchers, etc. Even though it would be nice, we definitely don’t need to support docs auto-generation for all possibilities. Nevertheless, we should be certain we will be able to add support gradually as the need arises without much trouble.
• Relatedly, it could be suitable to use an existing library for extracting JSDoc, if there's one (similarly to how vue-docgen-api is currently utilized for components)

The Value Add

Efficiency in creating new and maintaining existing documentation.

Possible Tradeoffs

Potential complexity of the task in light of currently having just few composables (as of July 2024). That’s one of the reasons this issue is scoped rather as exploration at this point.

Comments

If it seems that this idea is not feasible, in the scope of this issue we could at least consider how to make writing of the API section of the composable documentation more efficient, for example in the form of some new documentation utilities or components.