[FEATURE REQ] Analyzer fail docstrings linking deprecated methods.
- Dominant language
- C#
- Stars
- 135
- Forks
- 260
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 144
Description
**Library or service name.**
Analyzer for the libraries.
**The Problem**
- Azure Docs generator does not generate pages for deprecated (`[EditorBrowsable(EditorBrowsableState.Never)]`) methods/properties.
- There are plenty of links between docs.
- When a method becomes marked as deprecated, there are links to that method's docs which no longer work.
The above does not result in a broken link. A link is not rendered into the html. This appears to be by design. However that formatting is also what condenses the member to it's simple name, without namespace. When the link isn't rendered, the fully-qualified member name is displayed, where every method argument also displays its fully qualified type. These get quite long even without verbose namespaces or naming patterns (e.g. `Azure.Storage.Blobs.BlobClient.UploadAsync(System.IO.Stream,Azure.Storage.Blobs.Models.BlobHttpHeaders,System.Collections.Generic.IDictionary{System.String,System.String},Azure.Storage.Blobs.Models.BlobRequestConditions,System.IProgress{System.Int64},System.Nullable{Azure.Storage.Blobs.Models.AccessTier},Azure.Storage.StorageTransferOptions,System.Threading.CancellationToken)`). For context, most methods slated for deprecation in Azure.Storage.* are due to the conversions from long argument sequences to "options bag" signatures; the libraries will almost always run into this whenever a deprecation occurs.
This causes significant formatting issues that cascade across the entire webpage instead of just that section, making the page impossible to read.
**The Desired Solution**
An analyzer check on docstrings that fails CI when a non-deprecated public doc links to a deprecated member. This avoids the rendering error as well as keeps our docs up-to-date.
Contributor guide
Research direction
Start by locating the Azure Docs generator and the analyzer responsible for docstring links. Trace how deprecated members and public documentation links are handled, then define the CI failure for links from non-deprecated public docs to deprecated members; done means those references fail analysis before rendering creates unreadable pages.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- ci-cd, documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100