Fix all doxygen "X is not documented" warnings

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.

changed milestone to %Tor: unspecified

added component::core tor/tor doc easy milestone::Tor: unspecified owner::aomamemaki points::parent priority::medium severity::normal sponsor::U-can status::assigned tor-doc-lowlevel type::defect labels

Trac:
Reviewer: N/A to N/A
Sponsor: N/A to SponsorU-can

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

Trac:
Points: N/A to large,splittable

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

Trac:
Priority: Low to Medium

Trac:
Keywords: easy doc deleted, tor-doc-lowlevel, doc, easy added

This item needs subtickets.

Trac:
Points: large,splittable to parent

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

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

Trac:
Username: csucu

Trac:
Keywords: N/A deleted, isaremoved added
Milestone: Tor: 0.2.9.x-final to Tor: 0.2.???

Milestone renamed

Trac:
Milestone: Tor: 0.2.??? to Tor: 0.3.???

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

Trac:
Keywords: N/A deleted, tor-03-unspecified-201612 added
Milestone: Tor: 0.3.??? to Tor: unspecified

Remove an old triaging keyword.

Trac:
Keywords: tor-03-unspecified-201612 deleted, N/A added

Trac:
Keywords: isaremoved deleted, N/A added

Trac:
Username: aomamemaki
Status: new to assigned
Owner: N/A to aomamemaki

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

Trac:
Username: aomamemaki

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.

aomamemaki, are you working on this?

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

Trac:
Username: aomamemaki

moved to tpo/core/tor#18345 (closed)