[WIP] docs: Improve net comments #15672

pull dongcarl wants to merge 5 commits into bitcoin:master from dongcarl:2019-02-net-comments changing 1 files +27 −6

dongcarl commented at 10:46 PM on March 26, 2019: member

Improves comments for net, making them available to Doxygen. These improvements mostly focus on explaining return values, and out parameters.
docs: Improve GetLocal documentation 11454ce3fe
docs: Improve convertSeed6 inline documentation ec9cf63d28
docs: Improve AddLocal documentation f41c9d8e0a
docs: Improve SeenLocal documentation 78ac520bf6
docs: Improve GetBindAddress documentation bfb4a2787a
fanquake added the label Docs on Mar 26, 2019
practicalswift commented at 9:15 AM on March 27, 2019: contributor

Concept ACK

in src/net.cpp:355 in bfb4a2787a

 347 | @@ -332,7 +348,12 @@ bool CConnman::CheckIncomingNonce(uint64_t nonce)
 348 |      return true;
 349 |  }
 350 |  
 351 | -/** Get the bind address for a socket as CAddress */
 352 | +/**
 353 | + * Get the bind address for the specified socket as a CAddress.
 354 | + *
 355 | + * @returns The corresponding CAddress if the specified socket is valid and
 356 | + *          getsockname suceeded. Otherwise, the default CAddress.

practicalswift commented at 9:20 AM on March 27, 2019:

Should be "succeeded" :-)

promag commented at 4:11 PM on March 27, 2019: member

Concept ACK.
DrahtBot added the label Needs rebase on Apr 9, 2019
DrahtBot removed the label Needs rebase on Apr 11, 2019

in src/net.cpp:214 in bfb4a2787a

 206 | @@ -200,7 +207,12 @@ void AdvertiseLocal(CNode *pnode)
 207 |      }
 208 |  }
 209 |  
 210 | -// learn a new local address
 211 | +/**
 212 | + * Try to learn a new local service and its associated score, incrementing its
 213 | + * score if its address is already known.
 214 | + *
 215 | + * @returns Whether or not the new local service was learned.

jnewbery commented at 2:35 PM on May 28, 2019:

I'm not sure this is right. The function returns true even if the local service was already known. How about something like:

@returns true if the address is now in the mapLocalHost, false otherwise

dongcarl commented at 3:11 PM on May 28, 2019:

That's definitely more accurate. Thanks!

jnewbery commented at 3:05 PM on May 28, 2019: member

One comment inline. Otherwise looks good!
fanquake added the label Waiting for author on Jul 30, 2019
DrahtBot commented at 10:37 PM on August 5, 2019: member



The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.



Conflicts

No conflicts as of last run.
fanquake commented at 3:30 AM on August 19, 2019: member

Concept ACK. @dongcarl Can you fix-up the suggestions, and then probably mark this as ready for review?
dongcarl commented at 4:54 PM on August 19, 2019: member

I've got a few more comments to add, but it'll take a while. I'll close for now and open this later when I've got them sorted.
dongcarl closed this on Aug 19, 2019
laanwj removed the label Waiting for author on Oct 24, 2019
MarcoFalke locked this on Dec 16, 2021

Contributors

Labels

[WIP] docs: Improve net comments #15672

Conflicts