Hello!

With this PR I suggest formatting the features as

<span class="stab portability"><code>feature</code></span>

instead of

**`feature`**

so that they look the same as the ones automatically generated by rustdoc.

If you don't like this as default, I can put it behind a feature such as html-style or something...

The process of publishing a crate appears to naturally strip the comments in Cargo.toml.

Consequently, when i try to build and run the code in this crate from the published crate, i end up with errors in the self-test.

The published crate (v0.2.6) has this Cargo.toml:

# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO
#
# When uploading crates to the registry Cargo will automatically
# "normalize" Cargo.toml files for maximal compatibility
# with all versions of Cargo and also rewrite `path` dependencies
# to registry (e.g., crates.io) dependencies.
#
# If you are reading this file be aware that the original Cargo.toml
# will likely look very different (and much more reasonable).
# See Cargo.toml.orig for the original contents.

[package]
edition = "2018"
name = "document-features"
version = "0.2.6"
authors = ["Slint Developers <[email protected]>"]
description = "Extract documentation for the feature flags from comments in Cargo.toml"
homepage = "https://slint-ui.com"
readme = "README.md"
keywords = [
    "documentation",
    "features",
    "rustdoc",
    "macro",
]
categories = ["development-tools"]
license = "MIT OR Apache-2.0"
repository = "https://github.com/slint-ui/document-features"

[lib]
path = "lib.rs"
proc-macro = true

[dependencies.litrs]
version = "0.2.3"
default-features = false

[features]
default = []
self-test = []

This of course results in:

error: Could not find documented features in Cargo.toml
 --> tests/self-doc.rs:3:5
  |
3 |     document_features::document_features!();
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: this error originates in the macro `document_features::document_features` (in Nightly builds, run with -Z macro-backtrace for more info)

This is a concern for me because i'm trying to package the document-features crate in debian, and the debian rust team is currently packaging based on the published crates.

Hi :wave:

I tried to add document-features to my project https://github.com/viridIT/vSMTP/compare/develop...doc/feature but I have this error : I believe this is a bug in the parser :bug:

error: Parse error while parsing line: [
  --> src/vsmtp/vsmtp-core/src/lib.rs:21:10
   |
21 | #![doc = document_features::document_features!()]
   |          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: this error originates in the macro `document_features::document_features` (in Nightly builds, run with -Z macro-backtrace for more info)

error: Compilation failed, aborting rustdoc

error: could not document `vsmtp`

Caused by:
  process didn't exit successfully: `rustdoc [...]

[features]
default = []
## the `spline_inverse()` code will check if the knot vector is
## monotonic in *debug* builds.
##
## ⚠️ This only works when using a *nightly* toolchain.
unstable = []

Expected MD output:

• unstable — the spline_inverse() code will check if the knot vector is monotonic in debug builds.

  ⚠️ This only works when using a nightly toolchain.

Actual MD output:

• unstable — the spline_inverse() code will check if the knot vector is monotonic in debug builds.

⚠️ This only works when using a nightly toolchain.

From the commit message:

Commit 056b0b7d09a4ed49e50182df216361397656425c removed the dependency syn.

In doing so it introduced a bug where the string literal passed to document_features!(feature_label = "...") is not parsed anymore and therefore in the generated Markdown we insert a representation of the string literal as it appears in the source code instead of its content.

For instance, with the call document_features!(feature_label = r#"foo\"#) we insert in the Markdown the text r#"foo\"# instead of foo\.

if the entry for the default feature spans multiple lines trying to run cargo doc will return an error:

error: Parse error while parsing dependency default 
 --> src/main.rs:1:10
  |
1 | #![doc = document_features::document_features!()]
  |          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: this error originates in the macro `document_features::document_features` (in Nightly builds, run with -Z macro-backtrace for more info)

error: Compilation failed, aborting rustdoc

minimal Cargo.toml & main.rs required for this behaviour:

[package]
name = "dt"
version = "0.1.0"
edition = "2021"

[features]
default = [
    "foo"
]

## Doc commment for this feature
foo = []

[dependencies]
document-features = "0.2.1"

#![doc = document_features::document_features!()]

fn main() {
    println!("Hello, world!");
}

if the Cargo.toml is instead changed to the following (default put into a single line), everything works:

[package]
name = "dt"
version = "0.1.0"
edition = "2021"

[features]
default = [ "foo" ]

## Doc commment for this feature
foo = []

[dependencies]
document-features = "0.2.1"

Hi, and thanks for a great crate!

The docs suggests adding this to your Cargo.toml:

## Enable this when building the docs
document-features = { version = "0.2", optional = true }

The problem with this is that it breaks cargo check:

7 | #![doc = document_features::document_features!()]
  |          ^^^^^^^^^^^^^^^^^ use of undeclared crate or module `document_features`

I would suggest updating the docs to instead just have

document-features = "0.2"

unless there is some way to get around the cargo check issue that I'm not aware of

This fixes an issue where get_balanced would be called in a table that isn't [features] or a dependency table.

To reproduce place below in a Cargo.toml above [features] and try building the docs

[package.metadata.release]
pre-release-replacements = [
  {test="## "},
]

close #10

My Cargo.toml is breaking on upgrade to 0.2.2

error: Parse error while parsing dependency pre-release-replacements : unbalanced source
  --> src/lib.rs:38:50
   |
38 | #![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
   |                                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: this error originates in the macro `document_features::document_features` (in Nightly builds, run with -Z macro-backtrace for more info)

Make LICENSE.txt a symlink to MIT, so that github will stay happy. It would be so nice if github actually understood SPDX expressions.

Let me be the annoying license guy again:-/

This is a quick follow-up to #12.

• It adds support for r##"..."## format strings.
• It makes sure there aren't any other tokens left after the format string.

Closes https://github.com/slint-ui/document-features/issues/7

There are two ways to successfully use document-features. One is to to have it as a mandatory dependency:

document-features = "0.2" + #![doc = document_features::document_features!()]

However, this adds a dependency that is only needed when building docs, which is unnecessary. The other way is to have it optional:

[package.metadata.docs.rs]
all-features = true

[dependencies]
document-features = { version = "0.2", optional = true }

#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]

This is more verbose, but means the document-features doesn't become a build dependency, which is great.

Unfortunately, the old docs had a mix with document-features = { version = "0.2", optional = true } + #![doc = document_features::document_features!()] which fails when you do cargo check.

In this PR I suggest we always use the more verbose (but in my opinion better) way: the optional dependency.

Because #![doc = document_features::document_features!()] is quite long and unnecessary repeats itself.

I think it'll be better to have something like document_features::get!(), extract, etc.