Opened 3 years ago

Last modified 6 months ago

#18345 assigned defect

Fix all doxygen "X is not documented" warnings

Reported by: teor Owned by: aomamemaki
Priority: Medium Milestone: Tor: unspecified
Component: Core Tor/Tor Version:
Severity: Normal Keywords: easy, doc, tor-doc-lowlevel
Cc: Actual Points:
Parent ID: Points: parent
Reviewer: Sponsor: SponsorU-can

Description

Quoting arma:

It occurred to me while looking at the doxygen comment for
router_is_already_dir_fetching_ds() that if we had something go through
and complain about all cases where there's a function argument that is
not mentioned by <b>parameter</b> (with the markup) in the doxygen
comment... we would end up with a lot of complaints.

We could fix this by placing <b></b> around documented parameters, and by documented undocumented parameters.

There might even be a way to semi-automatically do this using a script, and then clean up any mismatches.

Child Tickets

Change History (18)

comment:1 Changed 3 years ago by isabela

Sponsor: SponsorU-can

comment:2 Changed 3 years ago by nickm

Points: large,splittable

Marking this as large, but we can split it into many smaller pieces.

comment:3 Changed 3 years ago by nickm

Possible smaller pieces include file-by-file fixes, or something. Here's a breakdown of there the 'undocumented member' warnings are coming from:

      1 aes.h
      1 circuitmux_ewma.h
      1 circuitstats.h
      1 command.c
      1 crypto_pwbox.c
      1 dircollate.h
      1 dns.h
      1 microdesc.h
      1 ntmain.h
      1 rendclient.c
      1 replaycache.h
      1 util_process.h
      2 circuitbuild.h
      2 circuituse.c
      2 compat_threads.h
      2 crypto_format.c
      2 dirserv.h
      2 memarea.c
      2 onion_tap.h
      2 procmon.h
      2 reasons.c
      2 rendcache.c
      2 rendcommon.h
      2 rendservice.h
      2 rephist.h
      2 workqueue.c
      3 channeltls.h
      3 compat_libevent.c
      3 compat_openssl.h
      3 torint.h
      3 util_process.c
      4 circuitlist.c
      4 circuitlist.h
      4 compat_pthreads.c
      4 crypto_curve25519.h
      4 crypto_ed25519.h
      4 di_ops.c
      4 di_ops.h
      4 dircollate.c
      4 dns_structs.h
      4 fp_pair.h
      4 geoip.h
      4 hibernate.h
      4 log.c
      4 relay.c
      4 relay.h
      4 routerparse.h
      4 sandbox.c
      4 scheduler.h
      4 status.c
      4 transports.h
      4 util_format.c
      5 connection_edge.h
      5 entrynodes.c
      5 onion_fast.h
      6 circuitbuild.c
      6 circuitstats.c
      6 compat.h
      6 confparse.h
      6 crypto_curve25519.c
      6 dirvote.h
      6 keypin.c
      6 onion.c
      6 router.c
      6 statefile.c
      6 torgzip.c
      7 address.c
      7 backtrace.c
      7 connection_or.c
      7 entrynodes.h
      7 procmon.c
      7 sandbox.h
      8 aes.c
      8 buffers.c
      8 connection_edge.c
      8 connection_or.h
      8 hibernate.c
      8 rendcache.h
      9 channeltls.c
      9 crypto_s2k.c
      9 policies.h
      9 routerlist.h
     10 buffers.h
     10 compat.c
     10 microdesc.c
     10 networkstatus.h
     10 nodelist.h
     10 scheduler.c
     10 torlog.h
     11 addressmap.c
     11 directory.h
     11 ext_orport.c
     11 main.h
     11 nodelist.c
     11 onion.h
     11 onion_ntor.c
     11 policies.c
     11 rendservice.c
     12 control.h
     12 crypto.c
     12 networkstatus.c
     12 router.h
     13 container.c
     13 dirserv.c
     13 transports.c
     14 circpathbias.c
     14 circuitmux_ewma.c
     16 connection.c
     16 connection.h
     16 crypto_ed25519.c
     16 geoip.c
     16 util.c
     17 config.h
     18 dirvote.c
     19 address.h
     19 cpuworker.c
     22 dns.c
     23 config.c
     24 circuitmux.c
     24 crypto.h
     24 tortls.c
     24 tortls.h
     26 channel.c
     26 circuitmux.h
     26 directory.c
     26 rephist.c
     27 routerkeys.c
     30 control.c
     32 routerlist.c
     32 routerparse.c
     39 channel.h
     69 util.h
     92 main.c
    366 or.h

comment:4 Changed 3 years ago by nickm

Priority: LowMedium

comment:5 Changed 3 years ago by nickm

Keywords: tor-doc-lowlevel added

comment:6 Changed 3 years ago by nickm

Points: large,splittableparent

This item needs subtickets.

comment:7 Changed 3 years ago by nickm

(It's reasonable to do some of this in 0.2.9, but not all.)

comment:8 Changed 3 years ago by csucu

I think you could also just suppress the warnings, by setting the 'WARN_IF_UNDOCUMENTED' flag to no, in the doxyfile.

Last edited 3 years ago by csucu (previous) (diff)

comment:9 Changed 3 years ago by isabela

Keywords: isaremoved added
Milestone: Tor: 0.2.9.x-finalTor: 0.2.???

comment:10 Changed 2 years ago by teor

Milestone: Tor: 0.2.???Tor: 0.3.???

Milestone renamed

comment:11 Changed 2 years ago by nickm

Keywords: tor-03-unspecified-201612 added
Milestone: Tor: 0.3.???Tor: unspecified

Finally admitting that 0.3.??? was a euphemism for Tor: unspecified all along.

comment:12 Changed 22 months ago by nickm

Keywords: tor-03-unspecified-201612 removed

Remove an old triaging keyword.

comment:13 Changed 22 months ago by nickm

Keywords: isaremoved removed

comment:14 Changed 16 months ago by aomamemaki

Owner: set to aomamemaki
Status: newassigned

comment:15 Changed 16 months ago by aomamemaki

I am new. I hope directly assigning this ticket to myself is the right thing to do.

comment:16 Changed 16 months ago by nickm

It's fine. One thing to be aware of: this is a lot of work: we have a bunch of undocumented functions! It would probably be a good idea to submit documentation for a few at a time, rather than trying to do everything in one big patch.

comment:17 Changed 6 months ago by traumschule

aomamemaki, are you working on this?

comment:18 Changed 6 months ago by aomamemaki

traumschule, I have not had a chance to work on this -- feel free to reassign the ticket

Note: See TracTickets for help on using tickets.