Opened 4 months ago

Closed 4 months ago

Last modified 3 months ago

#32307 closed defect (fixed)

Most every C file needs a doxygen @file declaration

Reported by: nickm Owned by: nickm
Priority: Medium Milestone: Tor: 0.4.3.x-final
Component: Core Tor/Tor Version:
Severity: Normal Keywords: network-team-roadmap-november, s31-docs
Cc: nickm Actual Points: .1
Parent ID: #29214 Points: .1
Reviewer: dgoulet Sponsor: Sponsor31-can


Doxygen does not generate any documentation for files that do not say @file or \file. We have dozens of those right now.

Child Tickets

Change History (5)

comment:1 Changed 4 months ago by nickm

See #32306 for a ticket about writing rules to enforce this.

comment:2 Changed 4 months ago by nickm

Actual Points: .1
Status: assignedneeds_review

This is a comments-only set of changes, affecting doxygen output. There were about 130 files that doxygen was ignoring!

See branch ticket32308 with PR in .

I'm not sure whether this meets the threshold for what I might merge without review; it does seem a little larger than is intended by "editorial fixes" on our merge policy.

Some of the per-file documentation I added here could stand to be more verbose. If it's okay with the reviewer, I'd like to have a separate tickets about that. Without this minimal per-file documentation, all of the member documentation in each file remains ignored by Doxygen.

comment:3 Changed 4 months ago by dgoulet

Reviewer: dgoulet
Status: needs_reviewmerge_ready


comment:4 Changed 4 months ago by dgoulet

Resolution: fixed
Status: merge_readyclosed


comment:5 Changed 3 months ago by nickm

Parent ID: #32306#29214
Note: See TracTickets for help on using tickets.