Re: documentation structure
| От | Corey Huinker |
|---|---|
| Тема | Re: documentation structure |
| Дата | |
| Msg-id | CADkLM=eJkq0Y9f5w_HVFVerFMg_T1NB1LrkYh-ZBpcmU2_S3Cg@mail.gmail.com обсуждение исходный текст |
| Ответ на | Re: documentation structure (Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>) |
| Список | pgsql-hackers |
And it's very inconsistent. For example, some functions use <optional>
tags for optional parameters, others use square brackets, and some use
<literal>VARIADIC</literal> to indicate variadic parameters, others use
ellipses (sometimes in <optional> tags or brackets).
Having just written a couple of those functions, I wasn't able to find any guidance on how to document them with regards to <optional> vs [], etc. Having such a thing would be helpful.
While we're throwing out ideas, does it make sense to have function parameters and return values be things that can accept COMMENTs? Like so:
COMMENT ON FUNCTION function_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] ARGUMENT argname IS '....';
COMMENT ON FUNCTION function_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] RETURN VALUE IS '....';
I don't think this is a great idea, but if we're going to auto-generate documentation then we've got to store the metadata somewhere, and pg_proc.dat is already lacking relevant details.
В списке pgsql-hackers по дате отправления: