On 09.10.23 11:38, Stefan Kaltenbrunner wrote:
> I have not actually looked at the code of the filter itself but
> personally I'm not super happy with doing a C-based filter as part of
> our doxygen documentation generation step - that seems like an
> additional maintainance burden infrastrukcture wise - is there nothing
> more lightweight available(assuming we even want that)?
Hello, Stefan.
This indeed can require some maintenace, unfortunately. But I think it
is worth it! Please see screenshots in attachments. On the left there
are currently published doxygen, and on right is documentation I have
generated with John's config. (It doesn't show source, but I believe it
is discrepancy in config, not issue from filter).
There could be some false positive, like in this code:
/* Functions in access/index/amapi.c */
extern IndexAmRoutine *GetIndexAmRoutine(Oid amhandler);
extern IndexAmRoutine *GetIndexAmRoutineByAmId(Oid amoid, bool noerror);
Doxygen would concat `Functions in access/index/amapi.c` with actual
docs from .c file, and resulting docs would become:
> GetIndexAmRoutine - call the specified access method handler routine to get its IndexAmRoutine struct, which will be
palloc'din the caller's context.
>
> Functions in access/index/amapi.c.
>
> Note that if the amhandler function is built-in, this will not involve any catalog access. It's therefore safe to use
thiswhile bootstrapping indexes for the system catalogs. relcache.c relies on that.
>
> Definition at line 33 of file amapi.c.
But that's not big problem, IMHO. Better at least some docs misrendered,
than no comments in docs.
Other option would be to manually clean up documentation to provide more
concise comments. I can actually try doing it, few files at a time.
But that would damage git history and git-blame, unless we use
.git-blame-ignore-revs-entry
I have tested, and if we add such commit to ignoreblame, and don't
change actual line numbers, git-blame works fine.
So I have created draft patches(don't pay atention to commit message in
patch, it's just draft) with way, how this comemnts can be changed. It
can be done semi manually, with applying that filter by hands and then
commiting to git. I am willing to do that, if this option is preferable
over using filter during build process.
P.S. Editors, such as VsCode and CLion parses comments in any format and
show them as documentation, so if use standalone tool to view code
instead of Doxygen it is good experience. But having proper
documentation in Doxygen would help new people who haven't downloaded
code and configured IDE yet.
P.S. My original question was to have current doxygen config to be
published, like it was in 2008.
Regards,
Bohdan Mart.
