dotnet / dotnet/csharplang

[Proposal]: <preliminary> documentation element

Open
#8,971 0 comments 0 reactions 1 assignee Claimed by @DustinCampbell View on GitHub
Proposal champion
Dominant language
C#
Stars
12.7k
Forks
1.1k
Avg merge
11h 1m
Merged PRs (30d)
3

Description

* Discussion: https://github.com/dotnet/csharplang/discussions/8970

## Summary
[summary]: #summary

I propose updating the C# language specification to define `` as a section-level documentation element. This element is valuable in versioning strategies where APIs may be included in published binaries prior to being declared stable. One recent example is the `IOperation` APIs used by Roslyn. Defining the `` element provides several benefits to library authors and users:

* Library authors can validate the defined public API surface for both stable and preliminary APIs by updating PublicApiAnalyzer to account for ``
* Library users can avoid using preliminary APIs by installing an analyzer capable of identifying preliminary APIs in a uniform manner
* In cases where library users wish to use a preliminary API, analyzers can help users contain the usage scope to avoid possible negative impact on other parts of an application

:link: [preliminary (Sandcastle XML Comments Guide)](http://ewsoftware.github.io/XMLCommentsGuide/html/c16bece7-694e-48ca-802d-cf3ae9205c55.htm)
:link: [Breaking Changes Policy (Threading API Reference)](http://tunnelvisionlabs.github.io/dotnet-threading/docs-latest/html/e02b9881-f06b-4420-aace-71b176d635db.htm) (See the **Preliminary Features** section at the bottom)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.