Opened 3 months ago

Closed 3 months ago

Last modified 2 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

Description

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 3 months ago by nickm

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

comment:2 Changed 3 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 https://github.com/torproject/tor/pull/1476 .

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 3 months ago by dgoulet

Reviewer: dgoulet
Status: needs_reviewmerge_ready

ack!

comment:4 Changed 3 months ago by dgoulet

Resolution: fixed
Status: merge_readyclosed

Merged!

comment:5 Changed 2 months ago by nickm

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