Proposed documentation format for RPC methods.

[oxarbitrage]

As we start adding RPC methods to zebra we should agree in a documentation format for each of them, similar to what zcashd does for their methods, for example:

https://github.com/zcash/zcash/blob/v4.6.0-1/src/rpc/misc.cpp#L49-L73 ends up being deployed as https://zcash.github.io/rpc/getinfo.html

I am proposing the following format for Zebra to kick off the discussion:

name

description

zcashd reference: link

Result
{
}

Notes

For exmple, in the context of #3142 i made the following doc for getinfo:

    /// getinfo
    ///
    /// Returns software information from the RPC server running Zebra.
    ///
    /// zcashd reference: <https://zcash.github.io/rpc/getinfo.html>
    ///
    /// Result:
    /// {
    ///      "build": String, // Full application version
    ///      "subversion", String, // Zebra user agent
    /// }
    ///
    /// Note 1: We only expose 2 fields as they are the only ones needed for
    /// lightwalletd: <https://github.com/zcash/lightwalletd/blob/v0.4.9/common/common.go#L91-L95>
    ///
    /// Note 2: <https://zcash.github.io/rpc/getinfo.html> is outdated so it does not
    /// show the fields we are exposing. However, this fields are part of the output
    /// as shown in the following zcashd code:
    /// <https://github.com/zcash/zcash/blob/v4.6.0-1/src/rpc/misc.cpp#L86-L87>

[jvff]

I think that proposal is good. There are a few things that I'd suggest:

1. Have the first line be the description, because that's what appears in the summary in the documentation pages generated by rust-doc. Having the RPC method name there would make it a bit weird IMHO, because it would be something like: "get_info getinfo".
2. We could have the documentation link hide the URL in the documentation page and just show the name of the RPC method. Something like:

zcashd reference: [`getinfo`](https://zcash.github.io/rpc/getinfo.html)

3. I think the Result section is unnecessary, it could link directly to the returned type. The user can then click on the return type link to see the fields.

Returns software information from the RPC server running Zebra, inside a [`GetInfo`] type.

4. I'm not sure about the Note format in the example 🤔 Maybe it should be a markdown section?

# Notes

1. We only expose 2 fields as they are the only ones needed for
   lightwalletd: https://github.com/zcash/lightwalletd/blob/v0.4.9/common/common.go#L91-L95
2. [The zcashd reference](https://zcash.github.io/rpc/getinfo.html) is outdated so it does not
   show the fields we are exposing. However, these fields are part of the output
   as shown in the [zcashd code](https://github.com/zcash/zcash/blob/v4.6.0-1/src/rpc/misc.cpp#L86-L87).

5. We might want to have the return types have the notes as well. Maybe at least have a line like:

Please see the notes at the RPC method's documentation: [`getinfo`][`Rpc::get_info`].

[oxarbitrage]

I think all this suggestions are good and we should do them but i don't understand number 5. Do you think you can create a comment with the entire doc of getinfo or any other method so we can see the whole thing ?

[jvff]

Sure! What I meant with number 5 was that important notes should probably be in the documentation for the RPC method, which should be linked to from the return type:

pub trait Rpc {
    /// Returns software information from the RPC server running Zebra, inside a [`GetInfo`] type.
    ///
    /// zcashd reference: [`getinfo`](https://zcash.github.io/rpc/getinfo.html)
    ///
    /// # Notes
    /// 
    /// 1. We only expose 2 fields as they are the only ones needed for
    ///    lightwalletd: https://github.com/zcash/lightwalletd/blob/v0.4.9/common/common.go#L91-L95
    /// 2. [The zcashd reference](https://zcash.github.io/rpc/getinfo.html) is outdated so it does not
    ///    show the fields we are exposing. However, this fields are part of the output
    ///    as shown in the [zcashd code](https://github.com/zcash/zcash/blob/v4.6.0-1/src/rpc/misc.cpp#L86-L87).
    #[rpc(name = "getinfo")]
    fn get_info(&self) -> Result<GetInfo>;
}

/// Response to a `getinfo` RPC request.
/// 
/// Please see the notes at the RPC method's documentation: [`Rpc::get_info`].
pub struct GetInfo {
    /// Full application version.
    build: String,

    /// Zebra user agent.
    subversion: String,
}

[oxarbitrage]

Should we have a spot for parameters in the documentation ?

[teor2345]

Yes please, parameters and return types should be documented for every Rust function.

[oxarbitrage]

Yes please, parameters and return types should be documented for every Rust function.

This is in contradiction to what @jvff suggest and was accepted before, the suggestion was:

"I think the Result section is unnecessary, it could link directly to the returned type. The user can then click on the return type link to see the fields."

Also, for the parameters how do you want to be documented exactly (I will not like to work on this until a full example with everything is displayed in this discussion )

[jvff]

I think we can just say what the return type is, leaving the details (like individual fields) to the actual return type's documentation. So as long as the documentation links to the return type's documentation, that should probably be enough.

As for parameters, I have no opinion on it. If we want to add them to the documentation, what would be the formatting? Maybe a bullet list with the parameter name in backticks, a colon, then a small description? Should this be in the main body of the documentation or should it be in a separate # Parameters section? E.g.:

# Parameters

- `param1`: value used for something
- `param2`: name to use for something else

# Notes

...

[teor2345]

I think it would be simpler to copy the parameters we support from the zcashd RPC reference.

But I don't have a strong opinion here.

[teor2345]

This is in contradiction to what @jvff suggest and was accepted before, the suggestion was:

"I think the Result section is unnecessary, it could link directly to the returned type. The user can then click on the return type link to see the fields."

It's not a contradiction, linking to the response type is fine.

[teor2345]

Here is a draft of the documentation format, with all of the changes we discussed.
I also tried to simplify the format and the text.

Do we need to make any significant changes to this format?
(We can make minor changes in cleanup PRs later.)

Feel free to post draft PRs with this format any time, so we can see if it works.

Read method (no parameters):

pub trait Rpc {
    /// Returns software information from the RPC server, as a [`GetInfo`] JSON struct.
    ///
    /// zcashd reference: [`getinfo`](https://zcash.github.io/rpc/getinfo.html)
    ///
    /// # Notes
    ///
    /// [The zcashd reference](https://zcash.github.io/rpc/getinfo.html) might not show some fields
    /// in Zebra's [`GetInfo`]. Zebra uses the field names and formats from the
    /// [zcashd code](https://github.com/zcash/zcash/blob/v4.6.0-1/src/rpc/misc.cpp#L86-L87).
    ///
    /// Some fields from the zcashd reference are missing from Zebra's [`GetInfo`]. It only contains the fields
    /// [required for lightwalletd support.](https://github.com/zcash/lightwalletd/blob/v0.4.9/common/common.go#L91-L95)
    #[rpc(name = "getinfo")]
    fn get_info(&self) -> Result<GetInfo>;
}

/// Response to a `getinfo` RPC request.
/// 
/// See the notes for the [`Rpc::get_info` method].
pub struct GetInfo {
    /// Full application version.
    build: String,

    /// Zebra network user agent.
    subversion: String,
}

Write method with parameters:

pub trait Rpc {
    /// Sends the raw bytes of a signed transaction to the local node's mempool, if the transaction is valid.
    /// Returns the [`SentTransactionHash`] for the transaction, as a JSON string.
    ///
    /// zcashd reference: [`sendrawtransaction`](https://zcash.github.io/rpc/sendrawtransaction.html)
    ///
    /// # Parameters
    ///
    /// - `raw_transaction_hex`: (string, required) The hex-encoded raw transaction bytes.
    ///
    /// # Notes
    ///
    /// zcashd accepts an optional `allowhighfees` parameter. Zebra doesn't support this parameter,
    /// because lightwalletd doesn't use it.
    #[rpc(name = "sendrawtransaction")]
    fn send_raw_transaction(
        &self,
        raw_transaction_hex: String,
    ) -> BoxFuture<Result<SentTransactionHash>>;
}

/// Response to a `sendrawtransaction` RPC request.
///
/// Contains the hex-encoded hash of the sent transaction.
///
/// Also see the notes for the [`Rpc::send_raw_transaction` method].
pub struct SentTransactionHash(String);

[dconnolly]

Here is a draft of the documentation format, with all of the changes we discussed. I also tried to simplify the format and the text.

Do we need to make any significant changes to this format? (We can make minor changes in cleanup PRs later.)

Feel free to post draft PRs with this format any time, so we can see if it works.

Read method (no parameters):

pub trait Rpc {
    /// Returns software information from the RPC server, as a [`GetInfo`] JSON struct.
    ///
    /// zcashd reference: [`getinfo`](https://zcash.github.io/rpc/getinfo.html)
    ///
    /// # Notes
    ///
    /// [The zcashd reference](https://zcash.github.io/rpc/getinfo.html) might not show some fields
    /// in Zebra's [`GetInfo`]. Zebra uses the field names and formats from the
    /// [zcashd code](https://github.com/zcash/zcash/blob/v4.6.0-1/src/rpc/misc.cpp#L86-L87).
    ///
    /// Some fields from the zcashd reference are missing from Zebra's [`GetInfo`]. It only contains the fields
    /// [required for lightwalletd support.](https://github.com/zcash/lightwalletd/blob/v0.4.9/common/common.go#L91-L95)
    #[rpc(name = "getinfo")]
    fn get_info(&self) -> Result<GetInfo>;
}

/// Response to a `getinfo` RPC request.
/// 
/// See the notes for the [`Rpc::get_info` method].
pub struct GetInfo {
    /// Full application version.
    build: String,

    /// Zebra network user agent.
    subversion: String,
}

Write method with parameters:

pub trait Rpc {
    /// Sends the raw bytes of a signed transaction to the local node's mempool, if the transaction is valid.
    /// Returns the [`SentTransactionHash`] for the transaction, as a JSON string.
    ///
    /// zcashd reference: [`sendrawtransaction`](https://zcash.github.io/rpc/sendrawtransaction.html)
    ///
    /// # Parameters
    ///
    /// - `raw_transaction_hex`: (string, required) The hex-encoded raw transaction bytes.
    ///
    /// # Notes
    ///
    /// zcashd accepts an optional `allowhighfees` parameter. Zebra doesn't support this parameter,
    /// because lightwalletd doesn't use it.
    #[rpc(name = "sendrawtransaction")]
    fn send_raw_transaction(
        &self,
        raw_transaction_hex: String,
    ) -> BoxFuture<Result<SentTransactionHash>>;
}

/// Response to a `sendrawtransaction` RPC request.
///
/// Contains the hex-encoded hash of the sent transaction.
///
/// Also see the notes for the [`Rpc::send_raw_transaction` method].
pub struct SentTransactionHash(String);

I like it! 👍