rustdoc --json output format contains no doc comments

[Boscop]

What's the right way to invoke rustdoc so that it outputs in JSON format but also with doc comments?

I'm doing cargo +nightly rustdoc -- --output-format json -Z unstable-options and the resulting JSON file has "docs": null for all items! 😅

Please let me know how to tell rustdoc to include doc comments 🙂
Thanks 🙏

[fmease]

This might be an inlined cross-crate re-exports issue. CC @aDotInTheVoid cuz I'm not super familiar with the current limitations of rustdoc json.

[fmease]

A shot in the dark, I can reproduce your exact (?) issue with:

rustc dep.rs --crate-type lib:

/// These are some docs!
pub struct S;

rustdoc usr.rs --edition 2021 -Lcrate=. --extern dep --output-format json -Zunstable-options:

pub use dep::*;

[aDotInTheVoid]

@fmease what output are you expecting for your example? it looks right to me:

  "index": {
    "0:0:2117": {
      "attrs": [],
      "crate_id": 0,
      "deprecation": null,
      "docs": null,
      "id": "0:0:2117",
      "inner": {"module": {"is_crate": true, "is_stripped": false, "items": ["0:3-20:0:2116"]}},
      "links": {},
      "name": "usr",
      "span": {"begin": [1, 0], "end": [1, 15], "filename": "usr.rs"},
      "visibility": "public"
    },
    "0:3-20:0:2116": {
      "attrs": [],
      "crate_id": 0,
      "deprecation": null,
      "docs": null,
      "id": "0:3-20:0:2116",
      "inner": {"import": {"glob": true, "id": "20:0:2116", "name": "dep", "source": "dep"}},
      "links": {},
      "name": null,
      "span": {"begin": [1, 0], "end": [1, 15], "filename": "usr.rs"},
      "visibility": "public"
    }
  },

The struct S doesn't appear in the docs because it's not defined in the crate being documented (and rustdoc-json doesn't inline re-exports).

---

@Boscop can you share reproduction instructions? Those flags look correct.

[Boscop]

@aDotInTheVoid With those flags I don't get ANY doc comments in the rustdoc json output. The doc comments are only in the html output, but not in the JSON output. So reproduction instructions are basically to have some doc comments on items in a crate and run that command on it and compare with the html doc output.

[aDotInTheVoid]

Hmm, I can't reproduce this. I attempted to with the following code:

// file: src/lib.rs

/// Here are the docs
pub struct ThisHasDocs;

Then building with cargo on latest nightly:

$ rustc +nightly -vV
rustc 1.83.0-nightly (eb4e23467 2024-10-09)
binary: rustc
commit-hash: eb4e2346748e1760f74fcaa27b42431e0b95f8f3
commit-date: 2024-10-09
host: aarch64-unknown-linux-gnu
release: 1.83.0-nightly
LLVM version: 19.1.1
$ cargo +nightly rustdoc -- --output-format json -Z unstable-options
 Documenting commment-demo v0.1.0 (/home/gh-aDotInTheVoid/tmp/commment-demo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.62s

which produces JSON output which contains the following:

  "index": {
    "0:0:2501": {
      "attrs": [],
      "crate_id": 0,
      "deprecation": null,
      "docs": null,
      "id": "0:0:2501",
      "inner": {"module": {"is_crate": true, "is_stripped": false, "items": ["0:3:2500"]}},
      "links": {},
      "name": "commment_demo",
      "span": {"begin": [1, 0], "end": [2, 23], "filename": "src/lib.rs"},
      "visibility": "public"
    },
    "0:3:2500": {
      "attrs": [],
      "crate_id": 0,
      "deprecation": null,
      "docs": "Here are the docs",
      "id": "0:3:2500",
      "inner": {
        "struct": {
          "generics": {"params": [], "where_predicates": []},
          "impls": [
            "a:2:27196:251-0:3:2500",
            "a:2:3414:263-0:3:2500",
            "a:2:3449:7740-0:3:2500",
            "a:2:27254:2773-0:3:2500",
            "a:2:37047:2877-0:3:2500",
            "a:2:37048:3236-0:3:2500",
            "b:2:2866-0:3:2500",
            "b:2:2869-0:3:2500",
            "b:2:3181-0:3:2500",
            "b:2:3185-0:3:2500",
            "b:2:3191-0:3:2500",
            "b:2:3196-0:3:2500",
            "b:2:4061-0:3:2500"
          ],
          "kind": "unit"
        }
      },
      "links": {},
      "name": "ThisHasDocs",
      "span": {"begin": [2, 0], "end": [2, 23], "filename": "src/lib.rs"},
      "visibility": "public"
    }

This has the doc comment that you expect!

If this somehow doesn't work for you, please included detailed reproduction steps including:

1. The rustdoc version
2. The code being documented
3. The full JSON output.