Merge pull request #1580 from MicrosoftEdge/api-spec-template-update

Update API spec template with changes to Project Reunion's template

Author: david-risney

specs/template.md

@@ -1,33 +1,63 @@
-<!-- USAGE
-  * Fill in each of the sections (like Background) below
-  * Wrap code with `single line of code` or ```code block```
-  * Before submitting, delete all <!-- TEMPLATE marked comments in this file,
+<!-- 
+    Before submitting, delete all "<!-- TEMPLATE" marked comments in this file,
     and the following quote banner:
 -->
 > See comments in Markdown for how to use this spec template
 
 <!-- TEMPLATE
-  The purpose of this spec is to describe a new WebView2 feature and its APIs.
-
-  There are two audiences for the spec. The first are people
-  that want to evaluate and give feedback on the API, as part of
-  the submission process. When it's complete
-  it will be incorporated into the public documentation at
-  docs.microsoft.com (https://docs.microsoft.com/en-us/microsoft-edge/webview2/).
-  Hopefully we'll be able to copy it mostly verbatim.
-  So the second audience is everyone that reads there to learn how
-  and why to use this API. 
+    The purpose of this spec is to describe new APIs, in a way
+    that will transfer to docs.microsoft.com (https://docs.microsoft.com/en-us/microsoft-edge/webview2/).
+
+    There are two audiences for the spec. The first are people that want to evaluate and
+    give feedback on the API, as part of the submission process.
+    So the second audience is everyone that reads there to learn how and why to use this API.
+    Some of this text also shows up in Visual Studio Intellisense.
+    When the PR is complete, the content within the 'Conceptual Pages' section of the review spec will be incorporated into the public documentation at
+    http://docs.microsoft.com (DMC).
+
+    For example, much of the examples and descriptions in the `RadialGradientBrush` API spec
+    (https://github.com/microsoft/microsoft-ui-xaml-specs/blob/master/active/RadialGradientBrush/RadialGradientBrush.md)
+    were carried over to the public API page on DMC
+    (https://docs.microsoft.com/windows/winui/api/microsoft.ui.xaml.media.radialgradientbrush?view=winui-2.5)
+
+    Once the API is on DMC, that becomes the official copy, and this spec becomes an archive.
+    For example if the description is updated, that only needs to happen on DMC and needn't
+    be duplicated here.
+
+    Examples:
+    * New set of classes and APIs (Custom Downloads):
+      https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/CustomDownload.md
+    * New member on an existing class (BackgroundColor):
+      https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/BackgroundColor.md
+
+    Style guide:
+    * Use second person; speak to the developer who will be learning/using this API.
+    (For example "you use this to..." rather than "the developer uses this to...")
+    * Use hard returns to keep the page width within ~100 columns.
+    (Otherwise it's more difficult to leave comments in a GitHub PR.)
+    * Talk about an API's behavior, not its implementation.
+    (Speak to the developer using this API, not to the team implementing it.)
+    * A picture is worth a thousand words.
+    * An example is worth a million words.
+    * Keep examples realistic but simple; don't add unrelated complications.
+    (An example that passes a stream needn't show the process of launching the File-Open dialog.)
+    * Use GitHub flavored Markdown: https://guides.github.com/features/mastering-markdown/
+
 -->
 
+Title
+===
 
 # Background
 <!-- TEMPLATE
     Use this section to provide background context for the new API(s)
-    in this spec. 
+    in this spec. Try to briefly provide enough information to be able to read
+    the rest of the document.
 
     This section and the appendix are the only sections that likely
     do not get copied into any official documentation, they're just an aid
-    to reading this spec. 
+    to reading this spec. If you find useful information in the background
+    or appendix consider moving it to documentation.
     
     If you're modifying an existing API, included a link here to the
     existing page(s) or spec documentation.
@@ -40,15 +70,24 @@
     the reader "go read 100 pages of background information posted at ...". 
 -->
 
-In this document we describe the updated API. We'd appreciate your feedback.
+# Conceptual pages (How To)
 
+_(This is conceptual documentation that will go to docs.microsoft.com "how to" page)_
 
-# Description
 <!-- TEMPLATE
-    Use this section to provide a brief description of the feature.
+    (Optional)
+
+    All APIs have reference docs, but some APIs or groups of APIs have an additional high level,
+    conceptual page (called a "how-to" page). This section can be used for that content.
+
+    For example, there are several navigation events each with their own reference doc, but then
+    there's also a concept doc on navigation
+    (https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/navigation-events).
 
-    For an example, see the introduction to the PasswordBox control
-    (http://docs.microsoft.com/windows/uwp/design/controls-and-patterns/password-box).
+    Sometimes it's difficult to decide if text belongs on a how-to page or an API page.
+    Because our API reference documentation is automatically turned into reference docs you can
+    lean towards including text in the API documentation below instead of in this conceptual
+    section.
 -->
 
 
@@ -57,6 +96,7 @@ In this document we describe the updated API. We'd appreciate your feedback.
     Use this section to explain the features of the API, showing
     example code with each description in both C# (for our WinRT API or .NET API) and
     in C++ for our COM API. Use snippets of the sample code you wrote for the sample apps.
+    The sample code for C++ and C# should demonstrate the same thing.
 
     The general format is:
 
@@ -100,78 +140,69 @@ In this document we describe the updated API. We'd appreciate your feedback.
     }
     ```
 
-    As an example of this section, see the Examples section for the PasswordBox
-    control (https://docs.microsoft.com/windows/uwp/design/controls-and-patterns/password-box#examples). 
--->
-
-
-# Remarks
-<!-- TEMPLATE
-    Explanation and guidance that doesn't fit into the Examples section.
-
-    APIs should only throw exceptions in exceptional conditions; basically,
-    only when there's a bug in the caller, such as argument exception.  But if for some
-    reason it's necessary for a caller to catch an exception from an API, call that
-    out with an explanation either here or in the Examples
--->
-
-
-# API Notes
-<!-- TEMPLATE
-    Option 1: Give a one or two line description of each API (type and member),
-        or at least the ones that aren't obvious from their name. These
-        descriptions are what show up in IntelliSense. For properties, specify
-        the default value of the property if it isn't the type's default (for
-        example an int-typed property that doesn't default to zero.) 
-        
-    Option 2: Put these descriptions in the below API Details section,
-        with a "///" comment above the member or type. 
+    As an example of this section, see the Examples section for the Custom Downloads
+    APIs (https://github.com/MicrosoftEdge/WebView2Feedback/blob/master/specs/CustomDownload.md). 
 -->
 
-
 # API Details
 <!-- TEMPLATE
     The exact API, in IDL format for our COM API and
     in MIDL3 format (https://docs.microsoft.com/en-us/uwp/midl-3/)
-    when possible, or in C# if starting with an API sketch for our .NET and WinRT API.
+    when possible.
 
     Include every new or modified type but use // ... to remove any methods,
     properties, or events that are unchanged.
 
+    For the MIDL3 parts, after running build-apiwriter, open the generated
+    `Microsoft.Web.WebView2.Core.idl` and find the new or modified portions
+    generated from your modifications to the COM IDL.
+
     (GitHub's markdown syntax formatter does not (yet) know about MIDL3, so
     use ```c# instead even when writing MIDL3.)
 
     Example:
     
-    ```
-    /// Event args for the NewWindowRequested event. The event is fired when content
-    /// inside webview requested to open a new window (through window.open() and so on.)
-    [uuid(34acb11c-fc37-4418-9132-f9c21d1eafb9), object, pointer_default(unique)]
-    interface ICoreWebView2NewWindowRequestedEventArgs : IUnknown
+```
+[uuid(B625A89E-368F-43F5-BCBA-39AA6234CCF8), object, pointer_default(unique)]
+interface ICoreWebView2Settings4 : ICoreWebView2Settings3 {
+  /// The IsPinchZoomEnabled property enables or disables the ability of 
+  /// the end user to use a pinching motion on touch input enabled devices
+  /// to scale the web content in the WebView2. It defaults to TRUE.
+  /// When set to FALSE, the end user cannot pinch zoom.
+  /// This API only affects the Page Scale zoom and has no effect on the
+  /// existing browser zoom properties (IsZoomControlEnabled and ZoomFactor)
+  /// or other end user mechanisms for zooming.
+  ///
+  /// \snippet SettingsComponent.cpp TogglePinchZooomEnabled
+  [propget] HRESULT IsPinchZoomEnabled([out, retval] BOOL* enabled);
+  /// Set the IsPinchZoomEnabled property
+  [propput] HRESULT IsPinchZoomEnabled([in] BOOL enabled);
+}
+```
+
+```c# (but really MIDL3)
+namespace Microsoft.Web.WebView2.Core
+{
+    runtimeclass CoreWebView2Settings
     {
         // ...
 
-        /// Window features specified by the window.open call.
-        /// These features can be considered for positioning and sizing of
-        /// new webview windows.
-        [propget] HRESULT WindowFeatures([out, retval] ICoreWebView2WindowFeatures** windowFeatures);
+        [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings5")]
+        {
+            Boolean IsPinchZoomEnabled { get; set; };
+        }
     }
-    ```
-
-    ```c# (but really MIDL3)
-    public class CoreWebView2NewWindowRequestedEventArgs
-    {
-        // ...
-
-	       public CoreWebView2WindowFeatures WindowFeatures { get; }
-    }
-    ```
+}
+```
 -->
 
 
 # Appendix
 <!-- TEMPLATE
-    Anything else that you want to write down for posterity, but
-    that isn't necessary to understand the purpose and usage of the API.
-    For example, implementation details or links to other resources.
+  Anything else that you want to write down about implementation notes and for posterity,
+  but that isn't necessary to understand the purpose and usage of the API.
+  
+  This or the Background section are a good place to describe alternative designs
+  and why they were rejected, any relevant implementation details, or links to other
+  resources.
 -->