Re: Where can I find the doxyfile? - Mailing list pgsql-hackers

From Bohdan Mart
Subject Re: Where can I find the doxyfile?
Date
Msg-id a0f6fb64-43b7-4963-a989-5a83b5db0c74@gmail.com
Whole thread Raw
In response to Re: Where can I find the doxyfile?  (Stefan Kaltenbrunner <stefan@kaltenbrunner.cc>)
Responses Re: Where can I find the doxyfile?
List pgsql-hackers
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.
Attachment

pgsql-hackers by date:

Previous
From: Jelte Fennema
Date:
Subject: Re: Request for comment on setting binary format output per session
Next
From: Alvaro Herrera
Date:
Subject: Re: pg_resetwal: Corrections around -c option