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.

I have the following field:

  #[default(Url::parse("http://pictrs:8080").unwrap())]
  #[doku(example = "http://pictrs:8080")]
  pub url: Url,

It fails to comopile with the trait doku::Document is not implemented for url::Url. I would expect this to work, by doku using the explicitly provided example, which is already a string. Alternatively, Url implements ToString, so that could also be used with the default value.

Hi,

when creating a JSON representation of an initialized struct via doku::to_json_val(&Config::default());, fields that are marked with #[serde(skip_serializing)] are set to their respective type and not, as expected, to the corresponding value.

use doku::Document;
use serde::Serialize;

#[derive(Serialize, Document)]
struct Config {
    /// Database's host
    db_host: String,
    #[serde(skip_serializing)]
    skip_ser: String,
}

impl Default for Config {
    fn default() -> Self {
        Self {
            db_host: "localhost".to_string(),
            skip_ser: "skip_ser".to_string(),
        }
    }
}

fn main() {
    let doc = doku::to_json_val(&Config::default());
    // passes
    assert_eq!(
        r#"{
  // Database's host
  "db_host": "localhost",
  "skip_ser": "string"
}"#,
        doc
    );

    // fails
    assert_eq!(
        r#"{
  // Database's host
  "db_host": "localhost",
  "skip_ser": "skip_ser"
}"#,
        doc
    );
}

We have a config field that is only for debugging, and shouldnt be set in production. For that reason, it also shouldnt be included in the default config generated by doku. But I dont see any way to achieve that, even with #[default(None)] and no doku annotation its included in the output. Maybe the field could be skipped in that case, or there could be a separate #doku(skip) annotation.

You can see the code in this PR.

Minor thing but the example on https://docs.rs/doku/0.10.1/doku/ does not include the lines like #[doku(example = "localhost")] which made the example quite hard to understand! They appear correctly in the README on Github

$ cargo +stable --version
cargo 1.55.0 (32da73ab1 2021-08-23)

$ cargo +stable check
Compiling proc-macro2 v1.0.29
Compiling syn v1.0.77
Compiling unicode-xid v0.2.2
Compiling version_check v0.9.3
Compiling fnv v1.0.7
Compiling strsim v0.10.0
Compiling ident_case v1.0.1
Compiling serde_derive v1.0.130
Compiling serde v1.0.130
Compiling anyhow v1.0.44
Compiling proc-macro-error-attr v1.0.4
Compiling proc-macro-error v1.0.4
Checking quote v1.0.9
Checking darling_core v0.13.0
Checking doku-test v0.0.0 (/home/felix/workspace/doku/doku-test)
error[E0554]: `#![feature]` may not be used on the stable release channel
--> /home/felix/.cargo/registry/src/github.com-1ecc6299db9ec823/darling_core-0.13.0/src/lib.rs:2:38
|
2 | #![cfg_attr(feature = "diagnostics", feature(proc_macro_diagnostic))]
|                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0554`.
error: could not compile `darling_core` due to previous error
warning: build failed, waiting for other jobs to finish...
error: build failed

Disabling the "diagnostics" feature of darling_core fixes the problem. Could you please make a patch release with that change? :)

Compiling this code:

#[derive(Document)]
struct Foo {
  bar: Bar,
}

struct Bar;

... will throw the trait bound ... is not satisfied at Document - it'd be nice if we pointed out bar: Bar instead, as does e.g. Serde.

I think it would be nice if comments in the output could be on a separate line before the data. That gives more space for comments, and also allows for multi-line comments to be included.

Maybe there could be a parameter on doku::to_json() to choose between multiple predefined output formats.

The recently implemented generic parser was not working properly when any trait bounds were specified at the trait definition (instead of using a where clause), so like this:

struct Something<T: Trait> {
  /* ... */
}

This commit fixes the aforementioned bug.

A first working implementation of TOML pretty printer (issue #7). A new module toml has been created (which started as a copy of json so there is some duplicated code). In addition, all the tests have been modified to also produce and assert on toml output, too.

Some things that are still pending / under consideration:

• [ ] Try reducing duplicated code by moving it to a common module. One issue with this task is that in some files (e.g. formatting/*.rs) the code is practically the same but the documentation examples are different.
• [ ] Directly documenting anything other than a struct or an enum (e.g. an array or an optional) is not very useful and produces invalid TOML. Maybe we shouldn't allow this? For our tests, I have wrapped these types in a struct so that valid TOML is produced.
• [ ] The code uses panic!() at various points to avoid cases that can't be documented properly (and would panic even more if the task above is implemented). Consider modifying to_toml() and all underlying methods to return a Result.
• [ ] Consider making json, toml features so that the user can choose to not compile any printer that they don't want (although compile time is not very high anyway).

My current branch got a bit bigger than I initially planned, so here's one, larger merge request that:

• closes https://github.com/anixe/doku/issues/1
• closes https://github.com/anixe/doku/issues/2
• closes https://github.com/anixe/doku/issues/8

Status: most of the code is ready; just have to write a few more tests and polish-up the docs 😃

The TOML support is awesome! It would be cool if this project also supported RON. I've used it on several projects for configuration. It supports comments like TOML but is also good for nested data like JSON .

This code:

use serde::Serialize;

#[derive(Default, Serialize)]
struct Foo {
    #[serde(rename = "bar\"")]
    bar: String,
}

fn main() {
    println!("{}", serde_json::to_string_pretty(&Foo::default()).unwrap());
}

... returns:

{
  "bar\"": ""
}

... but Doku will document it in a wrong way:

{
  "bar"": "string"
}

We generate doku output using command doku::to_json_fmt_val(&fmt, &Settings::default(). But even so, the default values are completely ignored, and we need to specify #[doku(example = ...)] as well, which usually means writing the same thing twice.

For example this Rust code:

  /// Address where pictrs is available (for image hosting)
  #[default("http://pictrs:8080")]
  pub url: String,

Generates this output:

    # Address where pictrs is available (for image hosting)
    url: "string"

Additionally, i think it would make sense that specifying #[default(None)] for an Option would have the same effect as #[doku(skip)].