Document a binary?

[e-matteson]

edit(@jyn514): Mentoring instructions for this issue are here: #238 (comment)

My crate has a macro that defines structs, and I want the docs to include an example of one of those generated structs. My solution was to write a binary, src/bin/example.rs, that invokes the macro.

This works great when I run cargo doc. I see example listed in the crates sidebar, and it contains docs for the generated struct. However, it doesn't show up in docs.rs.

I tried adding this to Cargo.toml, but it didn't help:

[[bin]]
name = "example"
doc = true

Is there some magical argument I can pass using [package.metadata.docs.rs] that will make it document the binary? Any other suggestions?

[e-matteson]

I worked around this issue the same way the bitflags crate does: adding an example_generated.rs module that is only compiled when an example_generated feature is used, and telling docs.rs to use that feature:

[package.metadata.docs.rs]
features = [ "example_generated" ]

I'll leave this issue open for now even though my specific problem is solved, since it would still be useful to document whether docs.rs can handle binaries. But feel free to close it if that's more appropriate.

[pickfire]

@jyn514 Do we need to get an RFC for this to allow documentation for binary?

[jyn514]

@pickfire no, this does not need an RFC. To get this implemented, we need to

• Stop passing --lib to cargo
• Stop filtering out binary targets
• Decide what to do if there are multiple binaries. I think if one has default-run = true we should build that and otherwise fall back to building the library.
• Decide what to do if there is both a binary and a library. I think in that case we should only build the library.

Possibly we could also make the behavior configurable, although I'd rather avoid that in a first draft of the feature.

[jyn514]

I'm happy to mentor or take PRs for this but I won't have time to work on it myself in the near future.

[pickfire]

Now I am wondering what to document in a binary. I think it is possible to put what needs to be documented in lib.rs. I kinda forgot my reason to work on this.

But looking at the source section in docs.rs, I think it would be good if it shows the binary and examples probably? But IIRC cargo does not publish examples and binaries together.

[Nemo157]

Unless you are filtering them out explicitly Cargo will include the example and binaries into the packaged crate.

One issue with this is that the default binary and the library have the same target name, so you get a warning and lose the output from one if you build both:

The bin target `foo` in package `foo v0.1.0 (/tmp/tmp.zK3J7HRdS3/foo)` has the same output filename as the lib target `foo` in package `foo v0.1.0 (/tmp/tmp.zK3J7HRdS3/foo)`.
Colliding filename is: /tmp/tmp.zK3J7HRdS3/foo/target/doc/foo/index.html

I also think this could also need some work on the rustdoc side to make it first class:

1. It should be possible to generate documentation for actual examples, not having to put an example in as a binary. (Actually, it appears that putting doc = true on an example works, there's just no cargo doc flag to say to document an example).
2. The sidebar should distinguish between different crate types, right now all libraries and binaries are lumped together under a "Crates" heading, this could be divided into "Library crates" and "Binary crates" (and "Example crates" if that's supported).

(TBH I see much more usefulness out of being able to have documented examples than binaries, but they're very similar in implementation).

[pickfire]

@Nemo157 Ah, I didn't mean to document examples or binaries straight away, of course it might still be useful to document pub items in binary to show others like the command line arguments the application accepts.

What I meant is the examples seemed to be missing from https://docs.rs/crate/clap/2.33.1/source/

[Nemo157]

That’s because clap explicitly excludes its examples from being published:

exclude = ["examples/*", "clap-test/*", "tests/*", "benches/*", "*.png", "clap-perf/*", "*.dot"]

[pickfire]

Oh, sorry. I didn't notice that.