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.