search

toby / serde-bencode

Serde backed Bencode encoding/decoding library for Rust.
MIT License
65 stars 16 forks source link

Write better documentation #12

Closed toby closed 4 years ago

toby commented 6 years ago

We should be using better (some!) source code annotations to generate documentation for rustdoc/docs.rs.

ghost commented 4 years ago

I've started working on this. I have a couple questions, though.

  1. What kind inputs cause errors with ser::to* and de::from*? For example, according to serde_json's documentation, it fails when trying to serialize a map with non-string keys.
  2. There are a few data types that seem like they should not be part of the public api. Right now, I have them annotated with #[doc(hidden)], but I want to double check whether that's a good idea. The types I'm referring to are SerializeMap, BencodeAccess and StringSerializer. If these are, in fact, not part of the public api, then it should instead be listed as pub(crate).
toby commented 4 years ago

Thank you for this! Honestly, I haven't had time to work on this library for years so am not up to date with the latest from Serde. If you want to take a stab at how this would work, I'll happily review it and merge.

ghost commented 4 years ago

Alright, I think I was able to reasonably guess what errors should be listed. I've finished the doc comments for all the public interfaces. Should I add comments inside the more complex functions or just doc comment annotations?

ghost commented 4 years ago

Scratch that, I don't think there are any functions long enough to warrant any more work. I'll set up the pull request.