⚠️ Wrong JSDoc comments parsing

[chicoxyzzy]

There's a bug in the docs generator. If the header module comment and comment next to it are not divided by some code, generator (or Acorn?) thinks that they are comments for the same thing (usually the first documented function after the header comment block) and appends module header to the wrong place and the module header in the resulting MD got skipped. Please put imports or some top level constants in between until we find a better solution.

cc @heapwolf @jwerle @bcomnes

[jwerle]

@chicoxyzzy Can you please give a code example?

[bcomnes]

Was just about to ask. Can you give an example of a bad doc block, and an example of how to fix?

[chicoxyzzy]

// @ts-check
/**
 * @module Test.DOM-helpers
 *
 * Provides a test runner for Socket Runtime.
 *
 *
 * Example usage:
 * ```js
 * import { test } from 'socket:test/dom-helpers.js'
 * ```
 *
 */
// Based on @socketsupply/test-dom and vhs-tape.

const SECOND = 1000
const defaultTimeout = 5 * SECOND

/**
 * Converts querySelector string to an HTMLElement or validates an existing HTMLElement.
 *
 * @export
 * @param {string|Element} selector - A CSS selector string, or an instance of HTMLElement, or Element.
 * @returns {Element} The HTMLElement, Element, or Window that corresponds to the selector.
 * @throws {Error} Throws an error if the `selector` is not a string that resolves to an HTMLElement or not an instance of HTMLElement, Element, or Window.
 *
 */
export function toElement (selector) {
  if (typeof selector === 'string') selector = document.querySelector(selector)
  if (!(
    selector instanceof window.HTMLElement ||
    selector instanceof window.Element
  )) throw new Error('stringOrElement needs to be an instance of HTMLElement or a querySelector that resolves to a HTMLElement')
  return selector
}

// ... rest of code

notice this in between two comment blocks

const SECOND = 1000
const defaultTimeout = 5 * SECOND

✅ Result:

---

Now if we move those consts below the toElement function:

// @ts-check
/**
 * @module Test.DOM-helpers
 *
 * Provides a test runner for Socket Runtime.
 *
 *
 * Example usage:
 * ```js
 * import { test } from 'socket:test/dom-helpers.js'
 * ```
 *
 */
// Based on @socketsupply/test-dom and vhs-tape.

/**
 * Converts querySelector string to an HTMLElement or validates an existing HTMLElement.
 *
 * @export
 * @param {string|Element} selector - A CSS selector string, or an instance of HTMLElement, or Element.
 * @returns {Element} The HTMLElement, Element, or Window that corresponds to the selector.
 * @throws {Error} Throws an error if the `selector` is not a string that resolves to an HTMLElement or not an instance of HTMLElement, Element, or Window.
 *
 */
export function toElement (selector) {
  if (typeof selector === 'string') selector = document.querySelector(selector)
  if (!(
    selector instanceof window.HTMLElement ||
    selector instanceof window.Element
  )) throw new Error('stringOrElement needs to be an instance of HTMLElement or a querySelector that resolves to a HTMLElement')
  return selector
}

const SECOND = 1000
const defaultTimeout = 5 * SECOND

// ...rest of the code

1. DOM-helpers functions are inside the Test module, not Test.DOM-helpers module 👎
2. Test.DOM-helpers module header got prepended to the toElement JSDoc 👎
3. There's no <h1>Test.DOM-helpers</h1> header 👎