On 07.10.23 00:29, postgres@coyotebush.net wrote:
> Sometime earlier, I created a filter to annotate regular C comments as doxy
> comments. I'll attach it along with a sample doxyfile for running it. Just
> in case it looks useful.
>
> I've never been a big fan of Doxygen, but it seems to have gotten better
> over time. Now that some IDEs display doxy comments on hover, I'm beginning
> to appreciate it.
Thank you for providing this `flex` filter! It is actually useful. I've
tested it on one
file from postures source base, and it actually converted regular
comments to doc-comments! If this filter could be used by official
Doxygen generation of Postgres, it would highly increase quality
of online documentation of Postgres!
My initial idea was to create patches to upstream with changing comments
to documented comments, because current online dock is lacking comments,
but with this filter it would be unneeded, as documentation would be
able to
be generated from current sources!
To illustrate the point:
~~~~~~~~~~~
This function has Doxy style comment
```
src/interfaces/ecpg/compatlib/informix.c
672:/**
673- * initialize the struct, which holds the different forms
674- * of the long value
675- */
676-static int
677-initValue(long lng_val)
```
And it is rendered properly:
https://doxygen.postgresql.org/informix_8c.html#a0dad4c2ee52a831d3aa1bf1133e0e17d
But function like this
```
src/backend/foreign/foreign.c
/*
* get_foreign_server_oid - given a server name, look up the OID
*
* If missing_ok is false, throw an error if name not found. If true,
just
* return InvalidOid.
*/
Oid
get_foreign_server_oid(const char *servername, bool missing_ok)
```
https://doxygen.postgresql.org/foreign_8c.html#a7959c56969be440c25b62c3c98ce2a78
doesn't have rendered documentation.
P.S. Was this original message from postgres@coyotebush.net intended to
be sent on John's Morris behalf?
