Skip to content

Fixed documentation strings so the docs site can build #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from

Conversation

yougotwill
Copy link

  • When we have a constexpr the documentation builder still expects the docstring to have Inputs: None. We should probably update the script
// Fails

/// API: encrypt/ENCRYPT_DATA_OVERHEAD
///
/// This value contains the constant amount of extra bytes required for encryption as performed by
/// `encrypt()`/`decrypt()`/`encrypt_inplace()`/`decrypt_inplace()`.
///
/// That is, for some message `m`, encrypt_overhead() is the difference between m.size() and
/// encrypt(m).size().
constexpr size_t ENCRYPT_DATA_OVERHEAD = 40;  // ABYTES + NPUBBYTES

// Passes

/// API: encrypt/ENCRYPT_DATA_OVERHEAD
///
/// This value contains the constant amount of extra bytes required for encryption as performed by
/// `encrypt()`/`decrypt()`/`encrypt_inplace()`/`decrypt_inplace()`.
///
/// That is, for some message `m`, encrypt_overhead() is the difference between m.size() and
/// encrypt(m).size().
///
/// Inputs: None
///
constexpr size_t ENCRYPT_DATA_OVERHEAD = 40;  // ABYTES + NPUBBYTES
  • When we write a function docstring we don't account for more complex typings such as <const unsigned char>. The regex for RPC_START in the build script does not account for spaces. I tried tweaking it but it broke other things. So this is the current solution which I have seen elsewhere in the code base.
// Fails

/// API: base/ConfigBase::DictFieldProxy::operator=(std::span<const unsigned char>)

// Passes

/// API: base/ConfigBase::DictFieldProxy::operator

@jagerman
Copy link
Member

I opened #45 as an alternative to this that fixes the issues in the parser.

@@ -1263,6 +1263,9 @@ class ConfigBase : public ConfigSig {
///
/// Note that only *incomplete* partial sets are affected by this (and stored); we also
/// separately retain metadata about *completed* multipart sets (see MULTIPART_MAX_REMEMBER).
///
/// Inputs: None
///
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is caused by missing /// Member variable. (fixed in #45)

@@ -1272,6 +1275,9 @@ class ConfigBase : public ConfigSig {
///
/// Unlike MULTIPART_MAX_WAIT, such storage does not include the data itself, but merely the
/// (final) config hash and timestamp of the recombined parts needed for deduplication.
///
/// Inputs: None
///
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Likewise

@@ -62,6 +62,9 @@ void encrypt_inplace(
///
/// That is, for some message `m`, encrypt_overhead() is the difference between m.size() and
/// encrypt(m).size().
///
/// Inputs: None
///
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is indeed a parser problem; I've added a change in #45 that recognizes this as a constant automatically, but also adds a new /// Constant. stanza in cases where the constant might be too complex.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants