Compatibility with smart-default crate

[Nutomic]

First of all, thanks for this crate, its really useful!

I would like to use it to generate documentation for our config file. As you can see, this file has default values configured for most fields using the smart-default crate. It would be very nice if doku could use these defaults when generating its output.

[Patryk27]

Hi 🙂 Thanks for reporting, I think it should be doable - I'll try to hack something over the weekend 😄

[Patryk27]

Hi, I've pushed a few cool changes to https://github.com/anixe/doku/pull/6 - when you check-out that version:

[dependencies]
doku = { git = "https://github.com/anixe/doku", rev = "issue/1" }

... and use doku::to_json_val():

use doku::prelude::*;

#[derive(Doku)]
struct Person {
    name:    String,
    surname: String,
}

impl Default for Person {
    fn default() -> Self {
        Self {
            name:    "Alan".to_string(),
            surname: "Turing".to_string(),
        }
    }
}

fn main() {
    println!("{}", doku::to_json_val(&Person::default()));
}

... the pretty-printer should be able to extract values out of given object:

{
  "name": "string",    // Default value: Alan
  "surname": "string"  // Default value: Turing
}

(this example uses manual impl Default, but in reality the trait doesn't matter - as long as you can somehow get an instance of that object, ::to_json_val() should work.)

Currently the formatting is rather crude, but during the week I plan on implementing a few configurables so that users can choose between:

{
  // Default value: Alan
  "name": "string",

  // Default value: Turing
  "surname": "string"
}

and

{
  "name": "Alan",
  "surname": "Turing"
}

If you have some ideas on the output formatting you'd like, please lemme know - I'll see what I can do 🙂

[Nutomic]

Great! Its working, but I would really prefer for the value to be in the json, not in the comment. Right now there are two values shown for each item, which seems quite confusing.

Regarding formatting, its mainly about the comments. I would prefer if your pregenerated comments (for optional and default values) could be avoided entirely, and only comments from the source code be included. Cause in our case almost everything is optional, it would be easier to write manual comments for mandatory fields.

Thanks a lot for your work on this :)

[Patryk27]

Hi, if you have a few minutes, an alpha version is ready for testing 🚀 😄

[dependencies]
doku = { git = "https://github.com/anixe/doku", rev = "v0.10" }

I've implemented a few tunables when it comes to the documentation's look-n-feel, so you should be able to get the format you described with:

let fmt = doku::json::Formatting {
    auto_comments: AutoComments::none(),
    ..Default::default()
};

let val = Settings::default();

println!("{}", doku::to_json_fmt_val(&fmt, &val));

This is more or less beta quality for now, so please lemme know if you find any issues or have any more ideas regarding the formatting - though hopefully everything will just work ™️

Edit: fyi, the derive macro's name has been changed - now it's not #[derive(Doku)], but #[derive(Document)].

[Nutomic]

Great, thats all I need for my current use case, thanks a lot! We will probably merge it after your next release.

Quick question, is there a way to pass an array as example? Code looks like this:

  #[doku(example = "[\"instance1.tld\",\"instance2.tld\"]")]
  pub allowed_instances: Option<Vec<String>>,

The current example is a workaround, because neither vec!["a", "b"] nor ["a", "b"] work. But its not a big deal.

In the future I also want to use your library to document a much more complicated part of our code (with 20+ structs). So I might have a few more feature requests once I get to that.

[Patryk27]

#[doku(example = ["a", "b"])] should be doable - I'll try pushing it together with v0.10 🙂 Thanks for testing; I'll keep those issues around until I publish the next release.

[Patryk27]

@Nutomic 0.10 has been released 🙂

As for the array examples, now it's enough to simply pass example = multiple times:

#[doku(example = "instance1.tld")]
#[doku(example = "instance2.tld")]
pub allowed_instances: Option<Vec<String>>,