Why do we need `feature` in a doctest for an unstable API? Can it automatically inserted? Isn't the extra trouble partly responsible for scarse documentations for unstable APIs?

language design
1

make check-docs complained “error: use of unstable library feature XYZ.” to the doctests which I tried to add to an unstable core API.

In fact there doesn’t seem to be any doctests around unstable items in the stdlib. Am I not supposed to write any doctests? That is odd. Who can verify unstable APIs without some minimal documentation of which doctest is an important part?

Do I perhaps have to write something like this?

```
#![feature(xyz)]
fn main() {
  let x = Foo;
  assert!(x.f())
}
```
#[unstable(feature="xyz", since="1.9.0")]
impl Foo {
    fn f() -> bool { true }
}

If so, the feature attribute in the doctest is not only ugly but also confusing for git log because removing it after stabilization will clutter the history.

Doctests should be treated as something internal to the unstable API itself and automatically be exempted from feature thing.

2

That's not true. For example, str::char_at has examples. Although I would expect that unstable stuff has less documentation in general, including examples.

We already need #![feature(...)] everywhere else and have the git log clutter. Omitting them from the example just means you can't copy & paste the example. Actually, you already can't copy & paste the example because examples can already hide irrelevant stuff (e.g. the fn main() { stuff). However, you can click the "run" button which sends the complete example to the playpen. An argument could be made that #![feature(...)] should be hidden by convention, but I don't think adding special magic to doctests is good.

3

You're right, apparently my regex search was inaccurate.

Yeah, I'd propose so. It would be one of several good opportunities to eliminate duplications in the source code.

I even have an opinion that a doctest for foo::bar::Baz should get implicit use foo::bar::Baz inserted, but that's another topic.

4

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.