Add comment for clear_unconfirmed_slot() in blockstore.rs

[yhchiang-sol]

Summary of Changes

Add comment block for clear_unconfirmed_slot() in blockstore.rs
explaining what it does and which column family it modifies.

[carllin]

I would specify metadata in the SlotMeta struct, since the other column being deleted families are also technically metadata

Pull request has been modified.

[steviez]

I think you should use

/// documentation line 1
/// documentation line 2
/// ...

over

/**
 * documentation line 1
 * documentation line 2
 * ...
 */

for at least for pub functions. Documentation gets generated for the /// lines above and included docs.rs page. It is hard to say how many people may actually use this, but you can see what did / didn't get included by viewing:
https://docs.rs/solana-ledger/latest/solana_ledger/blockstore/struct.Blockstore.html

There aren't any in this PR, but for the other PR's that use @param, it looks like the preferred method is doing something like:

solana/test-validator/src/lib.rs

Line 254 in 5a28f61

/// `program_name` will also used to locate the BPF shared object in the current or fixtures

Here's the Rust documentation on this too:
https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html

[codecov]

Codecov Report

Merging #21837 (a4f94af) into master (033106e) will decrease coverage by 0.0%.
The diff coverage is n/a.

@@            Coverage Diff            @@
##           master   #21837     +/-   ##
=========================================
- Coverage    81.3%    81.3%   -0.1%     
=========================================
  Files         516      516             
  Lines      144217   144217             
=========================================
- Hits       117268   117251     -17     
- Misses      26949    26966     +17     

[steviez]

The content looks good to me; just the formatting changes to make it match Rust convention please !

[yhchiang-sol]

Thanks for the useful reference, @steviez. I will fix all the styles before merging the PRs.

Here's the Rust documentation on this too: https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html

I was referring to the rust comment style mentioned here: https://doc.rust-lang.org/reference/comments.html, where it says:

OUTER_LINE_DOC :
   /// (~/ ~[\n IsolatedCR]*)?

OUTER_BLOCK_DOC :
   /** (~* | BlockCommentOrDoc ) (BlockCommentOrDoc | ~[*/ IsolatedCR])* */

Since the comment is a block comment describing a function, I think it's probably better to use/** */. If we only have one or two lines, then /// is preferred.

Btw, can I know how I can compile/find the document into an html file so that I can see how it looks like?

[steviez]

I was referring to the rust comment style mentioned here: https://doc.rust-lang.org/reference/comments.html, where it says:

Nice, I actually hadn't seen this before so thanks for sharing!

Since the comment is a block comment describing a function, I think it's probably better to use/** */. If we only have one or two lines, then /// is preferred.

I don't have a strong preference one way or the other. It looks like core rust libraries use /// across the board (ie such as here). I guess more than anything, I prefer consistency and I don't think I've seen use of block comments elsewhere in monorepo (not that that is a reason not to)

Btw, can I know how I can compile/find the document into an html file so that I can see how it looks like?
For the documentation that gets scraped from source, you can just do that through cargo. Try:

cargo doc --no-deps --open

The directions at the README here are for building the docs at https://docs.solana.com/

[yhchiang-sol]

I guess more than anything, I prefer consistency and I don't think I've seen use of block comments elsewhere in monorepo (not that that is a reason not to)

Definitely! I am just double-checking on what is the mostly-used style in Rust.

https://doc.rust-lang.org/src/alloc/vec/mod.rs.html#410-426

This is a great reference! I will follow the style here.

Pull request has been modified.