Namespace Oqtane.Documentation

This namespace contains attributes like PublicApi which mark code as public, private, internal, etc. Depending on what attributes you add to your code it will appear in the generated docs, and possibly have a warning or something attached.

Typical use:

[PublicApi]
public class YourClass {
  // this will be documented without any special comments
  // because we're not using the <summary> tag
  public string Name;

  /// <summary>
  /// This will be documented with this text in the summary
  /// </summary>
  public string Something;

  /// <summary>
  /// This won't appear in the public documentation
  /// </summary>
  [PrivateApi("Don't publish this - should only be used internally")]
  public string InternalSpecialName;

  /// <summary>
  /// This will appear in the docs, but Work-In-Progress is clearly visible
  /// </summary>
  [WorkInProgressApi("We're not done yet, may change")]
  public string NotDoneYet;

  /// <summary>
  /// This will appear in the docs, but with a warning
  /// </summary>
  [InternalApi_DoNotUse_MayChangeWithoutNotice("This may help you, but please don't use it")]
  public string YouShouldKnowAboutThisButNotUseIt;
}

Classes

InternalApi_DoNotUse_MayChangeWithoutNotice

This attribute serves as metadata for other things to mark them as internal APIs. Use this on stuff you want to document publicly, but mark as internal so people are warned

PrivateApi

This attribute marks classes, methods, etc. as private APIs So they should not be publicly documented. By default, all APIs are private, so you only need this attribute on children of classes marked with [PublicApi].

PublicApi

This attribute marks classes, properties etc. as public APIs. Any API / code with this attribute will be published in the docs. You can apply it to anything, but usually you will only need it on classes.

WorkInProgressApi

This attribute marks APIs to be publicly documented with a clear warning that it's work in progress.