# pre-RFC? documentation markers for backwards compatible changes

**URL:** <https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455>\
**Category:** Uncategorized\
**Created:** [May 5, 2018, 10:53pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455 "2018-05-05T22:53:42Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![glandium](https://avatars.discourse-cdn.com/v4/letter/g/3d9bf3/32.png) [@glandium](https://internals.rust-lang.org/u/glandium)\
**Post date:** [May 5, 2018, 10:53pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/1 "2018-05-05T22:53:42Z")

</div>

I was starting to write a RFC to add some markers for `const fn`, but then I realized that was only the tip of the iceberg, and that I might as well try to address the problem more generally.

The rust standard library documentation does a great job indicating in what rust version features, types, methods have been added, so that developers can make informed decisions whether they can use APIs based on the baseline rust version they are targetting for compatibility.

However, it stops there. Developers can read when a particular method was added, but not when the particular signature they are looking at was.

For example, the nightly documentation for `Vec::new` says its signature is:

```rust
pub const fn new() -> Vec<T>

```

meaning one can do:

```rust
static mut MYVEC : Vec<u8> = Vec::new();

```

… but it doesn’t tell that `const` was added in 1.27.0. So this code is not valid before that version.

But const is not the only change that can happen to APIs: they can be made more generic than they were when they were first introduced, thanks to features like generics or default trait parameters.

I don’t have concrete examples to give, but consider the following:

```rust
fn foo(s: &str) { ... }
fn bar<T>(t: Vec<T>) { ... }

```

The following are backwards compatible changes:

```rust
fn foo<T: AsRef<str>>(s: T) {... }
fn bar<T, A: Alloc = Global>(t: Vec<T, A>) { ... }

```

I’m sure there are already plenty of examples of such changes in the standard library. One that comes to mind is how the `PartialEq` trait changed from being `trait PartialEq` to being `trait PartialEq<Rhs: ?Sized = Self>`, but that was before 1.0.

When I first thinking about this, with only const in mind, I was thinking we could extend the `#[stable]` attribute to add the information, but considering the latter examples, I’m not sure anymore. Maybe a documentation convention about how to document those changes is what’s needed here. But maybe the `since` in the `#[stable]` attribute should be changed whenever an API is modified, too. So that the documentation clearly indicates that the documented API is available in that version, and then the documentation itself can go on to say that simpler versions of the API were available in older versions.

---

<div class="post-metadata">

**Author:** ![Centril](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/centril/32/3334_2.png) [@Centril](https://internals.rust-lang.org/u/Centril)\
**Post date:** [May 6, 2018, 10:47am UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/2 "2018-05-06T10:47:32Z")

</div>

I propose:

```rust
#[stable(feature = "rust1", since = "1.0.0", modified = "2018-05-06")]

```

(or maybe a version number, but that become harder to track…)

---

<div class="post-metadata">

**Author:** ![MajorBreakfast](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/majorbreakfast/32/4015_2.png) [@MajorBreakfast](https://internals.rust-lang.org/u/MajorBreakfast)\
**Post date:** [May 6, 2018, 8:28pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/3 "2018-05-06T20:28:03Z")

</div>

> [@Centril](#):
>
> #[stable(feature = "rust1", since = "1.0.0", modified = "2018-05-06")]

@Centril That'd mean that only the one modification (the last?) can be listed.

---

<div class="post-metadata">

**Author:** ![Centril](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/centril/32/3334_2.png) [@Centril](https://internals.rust-lang.org/u/Centril)\
**Post date:** [May 6, 2018, 8:43pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/4 "2018-05-06T20:43:42Z")

</div>

Yeah; if you wanted more, you could potentially do something like:

```rust
#[stable(feature = "rust1", since = "1.0.0",
         modified("2018-05-06",
                  "2020-03-10",
                  ..)
        )]

```

---

<div class="post-metadata">

**Author:** ![glandium](https://avatars.discourse-cdn.com/v4/letter/g/3d9bf3/32.png) [@glandium](https://internals.rust-lang.org/u/glandium)\
**Post date:** [May 6, 2018, 9:33pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/5 "2018-05-06T21:33:57Z")

</div>

A date doesn’t seem usable. It would presumably be the date the change occurs, but that would only indicate when the change happened in nightly. Documentation readers would then have to guess what release that corresponds to, so, add 6 weeks and look for the release that happened after that.

The more I think about it, the more I think changing the `since` to reflect the version in which the current signature, combined with some standardized documentation pattern indicating the history of the API, is better overall. It also doesn’t require any change to rustdoc to make the information appear usefully to readers.

---

<div class="post-metadata">

**Author:** ![Centril](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/centril/32/3334_2.png) [@Centril](https://internals.rust-lang.org/u/Centril)\
**Post date:** [May 6, 2018, 9:46pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/6 "2018-05-06T21:46:24Z")

</div>

> [@glandium](#):
>
> Documentation readers would then have to guess what release that corresponds to, so, add 6 weeks and look for the release that happened after that.

Hmm... Couldn't rustdoc figure out what version the date corresponds to if it has access to the intervals? That seems easiest for libstd devs and best for users who read docs.

---

<div class="post-metadata">

**Author:** ![glandium](https://avatars.discourse-cdn.com/v4/letter/g/3d9bf3/32.png) [@glandium](https://internals.rust-lang.org/u/glandium)\
**Post date:** [May 6, 2018, 10:29pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/7 "2018-05-06T22:29:06Z")

</div>

How is that easier for libstd devs? Actually, dates are presumably worse because the day someone does a change is not the day the PR is merged. At least with a version, you have a 6 weeks window that is hard to miss, and the only risk is for things happen close to the switch to beta (but then, `since` already has the same risk).

---

<div class="post-metadata">

**Author:** ![Centril](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/centril/32/3334_2.png) [@Centril](https://internals.rust-lang.org/u/Centril)\
**Post date:** [May 6, 2018, 10:39pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/8 "2018-05-06T22:39:41Z")

</div>

> [@glandium](#):
>
> Actually, dates are presumably worse because the day someone does a change is not the day the PR is merged.

Oh right; My bad! I didn't consider this.

---

<div class="post-metadata">

**Author:** ![steveklabnik](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/steveklabnik/32/4524_2.png) [@steveklabnik](https://internals.rust-lang.org/u/steveklabnik)\
**Post date:** [May 9, 2018, 2:15pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/9 "2018-05-09T14:15:48Z")

</div>

So, I think this idea is interesting, but you all have already gotten into some of the issues here… I’m not entirely sure how to implement this, even if I think the concept is a good one.

---

<div class="post-metadata">

**Author:** ![kennytm](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/kennytm/32/161_2.png) [@kennytm](https://internals.rust-lang.org/u/kennytm)\
**Post date:** [May 9, 2018, 3:11pm UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/10 "2018-05-09T15:11:43Z")

</div>

I think something like this could work:

```rust
#[stable(feature = "rust1", since = "1.0.0", 
    updated(since = "1.1.0", note = "`forget` is now safe"),
    updated(since = "1.44.0", note = "`forget` is now a const fn"),
]
pub const fn forget<T>(t: T) {

```

Alternatively, since this marker is mainly for documentation, we could continue abuse the `#[doc]` attribute:

```rust
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(updated(since = "1.1.0", note = "`forget` is now safe"))]
#[doc(updated(since = "1.44.0", note = "`forget` is now a const fn"))]
pub const fn forget<T>(t: T) {

```

---

<div class="post-metadata">

**Author:** ![system](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/system/32/14092_2.png) [@system](https://internals.rust-lang.org/u/system)\
**Post date:** [March 25, 2019, 8:30am UTC](https://internals.rust-lang.org/t/pre-rfc-documentation-markers-for-backwards-compatible-changes/7455/11 "2019-03-25T08:30:09Z")

</div>

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