Re: Where can I find the doxyfile?
On 14.10.23 21:54, John Morris wrote: Thank you for trying the patch out and commenting on it. Thank you! I even didn't know such filters are possible, and after that googling filter for C/C++ didn't gave good results. I'm starting to think of it as a project. Here's a quick project statement. 👍 The purpose is to generate improved Doxygen output while making maximal use of how Postgres currently does program comments. Yes, it shouldn't alter existing workflow. * Provide options for other (non-html) output. (Which ones?) I guess for now it is not needed, there were only HTML doxygen. * Mention it in developer guidelines and provide sample code showing a "desired" commenting style. I think no changes are needed in guidelines at this point, just allow existing comments to be collected. In future some documentation from Doxygen style can be copied to describe how to document function's parameter, etc. Does that list seem complete? I don't want people to think we're imposing new standards or legislating new commenting styles. It's more a matter of describing what we currently do, maybe with some minor suggestions for improving. Yes, that's all I can think about at first stage, at least. Except last bullet is too much. Better to not impose any new standards at this point. Just get as much comments as possible from existing code-base. And allow people build it locally. Later on we can find problematic places where comments that should not be pulled are pulled, and add some syntax into filter to exclude such comments. This are places, like section comments, like: "all following fields are ***" But at first step it's just good to have as much as possible comments collected, even if some are misplaced. So done is better than perfect. Best regards, Bohdan Mart. OpenPGP_0xD72F9AC47D08E8B6.asc Description: OpenPGP public key OpenPGP_signature.asc Description: OpenPGP digital signature
Including Doxyfile and Meson script for docs into main source tree
Hello, Stefan! What do you think about this? See quoted message from John Morris. P.S. Also we would like you to provide currently used Doxyfile, as Postgres doxigen's home page no longer have link to download said file. Regards, Bohdan. On 14.10.23 21:54, John Morris wrote: Thank you for trying the patch out and commenting on it. I'm starting to think of it as a project. Here's a quick project statement. The purpose is to generate improved Doxygen output while making maximal use of how Postgres currently does program comments. Thinking in terms of specific steps, and adding to what you have mentioned: * Configure Doxyfile so it produces output similar to previous output. * Only build Doxygen output if requested * Don't compile the filter or configure the Doxyfile if they aren't needed * Include contrib in the sources to document * Provide options for other (non-html) output. (Which ones?) * Update Postgres documentation to include instructions for creating Doxygen output. * Mention it in developer guidelines and provide sample code showing a "desired" commenting style. Does that list seem complete? I don't want people to think we're imposing new standards or legislating new commenting styles. It's more a matter of describing what we currently do, maybe with some minor suggestions for improving. * John Morris
Re: Where can I find the doxyfile?
On 07.10.23 00:29, postg...@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 postg...@coyotebush.net intended to be sent on John's Morris behalf?
