Skip to content

Make DocBuilder migration in 44.0.0 easier #13764

Closed
@alamb

Description

@alamb

Is your feature request related to a problem or challenge?

Also related to

While working to reproduce the issue from @kylebarron here:

I had some compile errors because Documentation::new() has changed signature (it now has three required arguments) after this PR from @comphead

This was a bit confusing / annoying and then I had to go find what to do / how to make a section, etc

Describe the solution you'd like

Before we release 44 into the world I think we like to make the experience better / more obvious what downstream crates should do on upgrade

Describe alternatives you've considered

Alternate 1: restore DocumentationBuilder::new and add deprecation message

I propose renaming

  1. DocumentationBuilder::new to something else (like new_with_section)
  2. Add a new function named DocumentationBuilder::new or something that is `#[deprecated]``, following the deprecation guidelines to help users find the new API

The message should point them at

  1. Using the [user_doc] proc macro (e.g. this)
  2. Using the newly added DocumentationBuilder:new_with_section

Alternate 2: Add migration guide

Another alternate would be to start working on a 44.0.0 migration guide and include this. I think automatically telling people what to use would be bette.r

Additional context

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions