docs: gardening

packages/docker/build/flecks.hooks.js

@@ -23,7 +23,7 @@ export const hooks = {
    *
    * @param {string} dockerfile The content of the Dockerfile.
    *
-   * @returns The new content of the Dockerfile.
+   * @returns {string} The new content of the Dockerfile.
    * @invoke ComposedAsync
    */
   '@flecks/docker.Dockerfile': (dockerfile) => (

packages/dox/build/generate.js

@@ -109,6 +109,7 @@ exports.generateDocusaurusHookPage = (hooks) => {
         example,
         invoke,
         params,
+        returns,
       } = specification || {
         params: [],
       };
@@ -143,6 +144,14 @@ exports.generateDocusaurusHookPage = (hooks) => {
         });
         source.push('');
       }
+      if (returns) {
+        const {description, type} = returns;
+        source.push(`### Returns \`${type}\``);
+        source.push('');
+        source.push(`<p>${description.trim()}</p>`);
+        source.push('');
+        source.push('');
+      }
       if (implementations.length > 0 || invocations.length > 0) {
         source.push('<div className={styles.hooks}>');
         if (implementations.length > 0) {

packages/dox/build/visitors.js

@@ -258,7 +258,7 @@ exports.hookSpecificationVisitor = (fn) => (
         .map(({name}) => (name ? `invoke${name}` : 'invoke'));
       const [returns] = tags
         .filter(({tag}) => 'returns' === tag)
-        .map(({name, type}) => ({description: name, type}));
+        .map(({description, name, type}) => ({description: `${name} ${description}`, type}));
       fn({
         hook: key.value,
         description: description.trim(),

packages/react/build/flecks.hooks.js

@@ -5,11 +5,11 @@ export const hooks = {
    * Note: `req` will be only be defined when server-side rendering.
    * @param {http.ClientRequest} req The HTTP request object.
    * @invoke SequentialAsync
+   * @returns {[ReactContextProvider<Props>, Props]} An array where the first element is a React
+   * context provider and the second element is the `props` passed to the context provider.
    */
   '@flecks/react.providers': (req) => {
-    // Generally it makes more sense to separate client and server concerns using platform
+    return req ? serverSideProvider(req) : [SomeContext.Provider, {value: 'whatever'}];
-    // naming conventions, but this is just a small contrived example.
-    return req ? serverSideProvider(req) : clientSideProvider();
   },
   /**
    * Define root-level React components that are mounted as siblings on `#main`.