Azure / Azure/azure-sdk-tools

[FEATURE REQ] Analyzer fail docstrings linking deprecated methods.

Open
#1,799 0 comments 0 reactions 0 assignees View on GitHub
API Analyzer Client
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.