Parameters in `buildDocumentation` output?

[raine]

I'm seeing parameters being generated in this project's README, but when I use buildDocumentation, I'm not seeing function parameters in the output.

Am I missing something or are parameters not actually supported?

[peterpeterparker]

Can you share a code snippet for which you would expect documentation for parameters to be generated? That way, I can give it a try and help figure it out.

[raine]

Hey, thanks. For example,

export type Opts = {
  accountId: string;
};

export const getAccount = async (opts: Opts): Promise<void> => {};

import { buildDocumentation } from "tsdoc-markdown";

const entries = buildDocumentation({
  inputFiles: ["src/tsdoc-test.ts"],
  options: {
    compilerOptions: {
      strictNullChecks: true,
    },
    types: true,
    explore: true,
  },
});

[
  {
    name: 'Opts',
    documentation: '',
    type: '{\n  accountId: string;\n}',
    jsDocs: [],
    doc_type: 'type',
    fileName: 'src/tsdoc-test.ts'
  },
  {
    name: 'getAccount',
    documentation: '',
    type: '(opts: Opts) => Promise<void>',
    jsDocs: [],
    doc_type: 'function',
    fileName: 'src/tsdoc-test.ts'
  }
]

edit:

Btw, I noticed a bug where if a type is imported and used as a return type in a function like so: Promise<Account | undefined>, in the buildDocumentation output signature, the return type changes to Promise<any>.

Does this sound familiar? I may open a bug on that if I get to making a repro that can be shared.

[peterpeterparker]

Thanks!

For your original question, it's currently expected behavior. Without documentation, the parameters are indeed not outputted. However, if I add some comments, they will be included.

/**
 * Retrieves account information.
 *
 * @param opts - The options containing the account ID.
 * @returns A promise that resolves when the operation is complete.
 */
export const getAccount = async (opts: Opts): Promise<void> => {};

### :gear: getAccount

Retrieves account information.

| Function | Type |
| ---------- | ---------- |
| `getAccount` | `(opts: Opts) => Promise<void>` |

Parameters:

* `opts`: - The options containing the account ID.


[:link: Source](https://github.com/peterpeterparker/tsdoc-markdown/tree/main/src/test/mock.ts#L11)

I'm not sure I have any use case where I would want to output the type without providing related documentation. I don't know if it's really a use case that needs to be supported. What do you think?

Regarding Promise<any>, could you open a separate issue with a related code snippet? Happy to have a look.

[raine]

Ah, I see now how buildDocumentation expands the single option argument into multiple params.

https://github.com/peterpeterparker/tsdoc-markdown/blob/main/src/lib/docs.ts#L473C1-L482

I was kind of expecting it to parse the arguments from source code without TSDoc but I guess this makes sense.

Though I think sometimes you may not want to add JSDoc for an argument that only repeats the obvious that can be already inferred from the argument name and type.

[peterpeterparker]

I think it's a fair point. Maybe we can keep the issue open as 'low-hanging fruit' until someone else shares that they would gladly generate the parameters without JSDoc? Unless of course you need it right now to unblock something, in which case I can take a look.