Add Documentation attributes

part of https://github.com/oqtane/oqtane.framework/issues/570

Oqtane.Shared/Documentation/InternalApi.cs

@@ -0,0 +1,28 @@
+using System;
+
+namespace Oqtane.Documentation
+{
+    /// <summary>
+    /// 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
+    /// </summary>
+    [AttributeUsage(AttributeTargets.All, AllowMultiple = true, Inherited = false)]
+    [PublicApi]
+    // ReSharper disable once InconsistentNaming
+    public class InternalApi_DoNotUse_MayChangeWithoutNotice: Attribute
+    {
+        /// <summary>
+        /// The `[InternalApi_DoNotUse_MayChangeWithoutNotice]` attribute can be used without additional comment. 
+        /// </summary>
+        // Important note - this constructor looks unnecessary, because comment is optional in the other constructor
+        // but we need it because of a minor issue in docfx
+        public InternalApi_DoNotUse_MayChangeWithoutNotice() { }
+
+        /// <summary>
+        /// Constructor with optional comment `[InternalApi_DoNotUse_MayChangeWithoutNotice(some-comment)]`. 
+        /// </summary>
+        /// <param name="comment">Reason why it's internal, optional</param>
+        public InternalApi_DoNotUse_MayChangeWithoutNotice(string comment) { }
+
+    }
+}

Oqtane.Shared/Documentation/PrivateApi.cs

@@ -0,0 +1,27 @@
+using System;
+
+namespace Oqtane.Documentation
+{
+    /// <summary>
+    /// 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]`.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.All, AllowMultiple = true, Inherited = false)]
+    [PublicApi]
+    public class PrivateApi: Attribute
+    {
+        /// <summary>
+        /// The `[PrivateApi]` attribute can be used without additional comment. 
+        /// </summary>
+        // Important note - this constructor looks unnecessary, because comment could be optional in the other constructor
+        // but we need it because of a minor issue in docfx
+        public PrivateApi() { }
+
+        /// <summary>
+        /// Constructor with optional comment `[PrivateApi(some-comment)]`. 
+        /// </summary>
+        /// <param name="comment">Reason why it's private, optional</param>
+        public PrivateApi(string comment) { }
+    }
+}

Oqtane.Shared/Documentation/PublicApi.cs

@@ -0,0 +1,27 @@
+using System;
+
+namespace Oqtane.Documentation
+{
+    /// <summary>
+    /// 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. 
+    /// </summary>
+    [AttributeUsage(AttributeTargets.All, AllowMultiple = true, Inherited = false)]
+    [PublicApi]
+    public class PublicApi: Attribute
+    {
+        /// <summary>
+        /// The `[PublicApi]` attribute can usually be used without additional comment. 
+        /// </summary>
+        // Important note - this constructor looks unnecessary, because comment could be optional in the other constructor
+        // but we need it because of a minor issue in docfx
+        public PublicApi() { }
+
+        /// <summary>
+        /// Constructor with optional comment `[PublicApi(some-comment)]`
+        /// </summary>
+        /// <param name="comment">Reason why it's public, optional</param>
+        public PublicApi(string comment) { }
+    }
+}

Oqtane.Shared/Documentation/WorkInProgressApi.cs

@@ -0,0 +1,18 @@
+using System;
+
+namespace Oqtane.Documentation
+{
+    /// <summary>
+    /// This attribute marks APIs to be publicly documented with a clear warning that it's work in progress.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.All, AllowMultiple = true, Inherited = false)]
+    [PublicApi]
+    public class WorkInProgressApi: Attribute
+    {
+        /// <summary>
+        /// The `[WorkInProgressApi(some-comment)]` attributes must always have a comment why they are WIP.
+        /// </summary>
+        /// <param name="comment">Reason why it's WIP, required</param>
+        public WorkInProgressApi(string comment) { }
+    }
+}

Oqtane.Shared/Documentation/readme.md

@@ -0,0 +1,7 @@
+# Oqtane API Decorator Attributes
+
+This folder contains special attributes for the API Code Generator.
+
+The idea is that only items marked with special attributes are valide public APIs, and only these will be documented in the public docs 
+
+As of 2020, all APIs are documented, and only these marked as `[PrivateApi]` will be excluded. In future, we may reverse this to only document things marked as `[PublicApi]`.