document spork system with doxygen comments #2301

nmarley · 2018-09-17T18:35:21Z

This is an initial shot at an on-going WIP, which will add documentation via Doxygen comments to (especially) Dash-specific features in the codebase.

@UdjinM6 I will need some guidance on the rationale for GetSignatureHash, as you will see. 😉

gladcow

May be it is better to place method descriptions in header file and to place only some implementation-specific notes in cpp file?

nmarley · 2018-09-18T00:43:31Z

src/spork.cpp

@@ -316,6 +378,10 @@ bool CSporkMessage::Sign(const CKey& key, bool fSporkSixActive)
    return true;
 }

+/**
+ * CheckSignature will ensire the spork signature matches the provided public


s/ensire/ensure/

nmarley · 2018-09-18T00:44:03Z

src/spork.cpp

@@ -260,23 +308,37 @@ bool CSporkManager::SetPrivKey(const std::string& strPrivKey)
    }
 }

+/**
+ * ToString returns the string representations of the SporkManager.


"representations" should be singular

nmarley · 2018-09-18T00:49:28Z

May be it is better to place method descriptions in header file and to place only some implementation-specific notes in cpp file?

Thanks for the suggestion. I added them with the implementations because I thought that made more sense, but maybe the actual C++ way is to add them in the header files. Since the classes were declared in header files, that's where I added those class comments. Technically the methods are "declared" in the class definition (e.g. the function prototypes).

I guess the big questions (for me) are:

What is C++ convention for this?
Where are the comments more helpful?

~~It's possible doxygen also cares where these go.~~ Nope, looks like doxygen doesn't care. I see various opinions online. Wondering what others think.

PastaPastaPasta · 2018-09-18T01:05:48Z

What is C++ convention for this?

Doesn't seem like there is one that I can find.

Found this that makes sense (just some guys opinion):

Document how to use the function in the header file, or more accurately close to the declaration.
Document how the function works (if it's not obvious from the code) in the source file, or more accurately, close to the definition.

gladcow · 2018-09-18T06:20:18Z

What is C++ convention for this?

There is no common convention for comments, but there is google styleguide, for example, https://google.github.io/styleguide/cppguide.html#Function_Comments or such guide: http://www.edparrish.net/common/cppdoc.html. The most common practice is describe function goal and usage conditions in header and non-obvious implementation details in cpp file, I think.

Where are the comments more helpful?

Function description in header is more helpful: when you see unknown function in code, you are clicking Go To Definition in your IDE and goes to header file usually.)

nmarley · 2018-09-18T16:34:33Z

@gladcow The more I look over DashCore code, I'm realizing that I don't actually look in the header files. And in my IDE when I click to go to the function, it's taking me to the implementation (e.g. the cpp file), not the header declaration (I use CLion).

Personally I don't think it makes since to stick the documentation in the header files where I'm not even looking at the file. The comments make the most sense to me where the method is defined (not declared).

nmarley · 2018-09-18T16:39:28Z

@PastaPastaPasta I'm almost certain your random guy's opinion came from StackExchange, which I also found yesterday as well, while searching conventions. I also found others which differ, also on Stack Exchange, such as this one (which I tend to agree with):

Put the documentation where people will read and write it as they are using and working on the code.

Class comments go in front of classes, method comments in front of methods.

That is the best way to make sure things are maintained. It also keeps your header files relatively lean and avoids the touching issue of people updating method docs causing headers to be dirty and triggering rebuilds. I have actually known people use that as an excuse for writing documentation later!

nmarley · 2018-09-29T20:22:40Z

Rebased onto develop and moved method comments into header file per discussion. Also removed [WIP] tag, ready for review.

UdjinM6

Looks good. Will require a bit more work after #2288. Added a couple of notes, see comments below.

UdjinM6 · 2018-09-29T21:39:15Z

src/spork.h

@@ -75,15 +88,41 @@ class CSporkMessage
        }
    }

+    /**
+     * GetHash returns the double-sha256 hash of the serialized spork message. The


The signature field is not included in the serialization. this will not be true after #2288

UdjinM6 · 2018-09-29T21:40:32Z

src/spork.h

    uint256 GetHash() const;
+
+    /**
+     * GetSignatureHash is currently an alias for GetHash, and I'm not sure why it


I'm not sure why

The signature field is not included in the serialization. - that's why in this case ;)

UdjinM6 · 2018-09-29T21:43:14Z

src/spork.h

    bool UpdateSpork(int nSporkID, int64_t nValue, CConnman& connman);

+    /**
+     * IsSporkActive returns a bool for "on/off" sporks, which should be used to
+     * determine whether the spork can be considered active or not.


Should probably clarify that this is only true for time-based sporks (which are majority), for pure value-based sporks like SPORK_5_INSTANTSEND_MAX_VALUE this function makes no sense and should not be used.

nmarley · 2018-09-30T00:06:10Z

Fixed Get*Hash methods and added comment for CheckAndRemove, so that should be all (for now). I will start on the post-2288 work and rebase once that gets merged in.

This is an initial shot at an on-going WIP, which will add documentation via Doxygen comments to (especially) Dash-specific features in the codebase.

nmarley · 2018-09-30T17:47:51Z

Added comments for new methods introduced in #2288, squashed & rebased to resolve conflicts. Please re-review.

gladcow

ACK

UdjinM6

LGTM 👍

utACK

This is an initial shot at an on-going WIP, which will add documentation via Doxygen comments to (especially) Dash-specific features in the codebase.

gladcow reviewed Sep 17, 2018

View reviewed changes

nmarley commented Sep 18, 2018

View reviewed changes

nmarley force-pushed the spork-docs branch from 6fd6498 to 56b3e83 Compare September 29, 2018 20:21

nmarley changed the title ~~[WIP] document spork system with doxygen comments~~ document spork system with doxygen comments Sep 29, 2018

UdjinM6 added this to the 12.4 milestone Sep 29, 2018

UdjinM6 reviewed Sep 29, 2018

View reviewed changes

document spork system with doxygen comments

e247410

This is an initial shot at an on-going WIP, which will add documentation via Doxygen comments to (especially) Dash-specific features in the codebase.

nmarley force-pushed the spork-docs branch from e1dcff6 to e247410 Compare September 30, 2018 17:46

gladcow approved these changes Oct 1, 2018

View reviewed changes

UdjinM6 approved these changes Oct 1, 2018

View reviewed changes

UdjinM6 merged commit 07208a4 into dashpay:develop Oct 2, 2018

nmarley deleted the spork-docs branch October 3, 2019 12:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

document spork system with doxygen comments #2301

document spork system with doxygen comments #2301

nmarley commented Sep 17, 2018

gladcow left a comment

nmarley Sep 18, 2018

nmarley Sep 18, 2018

nmarley commented Sep 18, 2018

PastaPastaPasta commented Sep 18, 2018

gladcow commented Sep 18, 2018 •

edited

Loading

nmarley commented Sep 18, 2018

nmarley commented Sep 18, 2018

nmarley commented Sep 29, 2018 •

edited

Loading

UdjinM6 left a comment

UdjinM6 Sep 29, 2018

UdjinM6 Sep 29, 2018

UdjinM6 Sep 29, 2018

nmarley commented Sep 30, 2018

nmarley commented Sep 30, 2018

gladcow left a comment

UdjinM6 left a comment

document spork system with doxygen comments #2301

document spork system with doxygen comments #2301

Conversation

nmarley commented Sep 17, 2018

gladcow left a comment

Choose a reason for hiding this comment

nmarley Sep 18, 2018

Choose a reason for hiding this comment

nmarley Sep 18, 2018

Choose a reason for hiding this comment

nmarley commented Sep 18, 2018

PastaPastaPasta commented Sep 18, 2018

gladcow commented Sep 18, 2018 • edited Loading

nmarley commented Sep 18, 2018

nmarley commented Sep 18, 2018

nmarley commented Sep 29, 2018 • edited Loading

UdjinM6 left a comment

Choose a reason for hiding this comment

UdjinM6 Sep 29, 2018

Choose a reason for hiding this comment

UdjinM6 Sep 29, 2018

Choose a reason for hiding this comment

UdjinM6 Sep 29, 2018

Choose a reason for hiding this comment

nmarley commented Sep 30, 2018

nmarley commented Sep 30, 2018

gladcow left a comment

Choose a reason for hiding this comment

UdjinM6 left a comment

Choose a reason for hiding this comment

gladcow commented Sep 18, 2018 •

edited

Loading

nmarley commented Sep 29, 2018 •

edited

Loading