Rename FullyResolved to SymbolsFinalized and TryAddSymbolXxx to TryProcessSymbol

Plus fix up more documentation

4 files changed, 61 insertions, 79 deletions

diff --git a/src/WixToolset.Extensibility/BaseBurnBackendExtension.cs b/src/WixToolset.Extensibility/BaseBurnBackendExtension.cs
index 0575d725..488f882a 100644
--- a/src/WixToolset.Extensibility/BaseBurnBackendExtension.cs
+++ b/src/WixToolset.Extensibility/BaseBurnBackendExtension.cs
@@ -2,6 +2,7 @@
 
 namespace WixToolset.Extensibility
 {
+    using System;
     using System.Collections.Generic;
     using System.Linq;
     using WixToolset.Data;
@@ -35,24 +36,8 @@ namespace WixToolset.Extensibility
         protected virtual IEnumerable<IntermediateSymbolDefinition> SymbolDefinitions => Enumerable.Empty<IntermediateSymbolDefinition>();
 
         /// <summary>
-        /// Called after all output changes occur and right before the output is bound into its final format.
+        /// See <see cref="IBurnBackendExtension.PreBackendBind(IBindContext)"/>
         /// </summary>
-        public virtual void BundleFinalize()
-        {
-        }
-
-        /// <summary>
-        /// Called after output is bound into its final format.
-        /// </summary>
-        /// <param name="result"></param>
-        public virtual void PostBackendBind(IBindResult result)
-        {
-        }
-
-        /// <summary>
-        /// Called before binding occurs.
-        /// </summary>
-        /// <param name="context"></param>
         public virtual void PreBackendBind(IBindContext context)
         {
             this.Context = context;
@@ -61,44 +46,32 @@ namespace WixToolset.Extensibility
         }
 
         /// <summary>
-        /// 
+        /// See <see cref="IBurnBackendExtension.ResolveRelatedFile(String, String, String, SourceLineNumber)"/>
         /// </summary>
-        /// <param name="source"></param>
-        /// <param name="relatedSource"></param>
-        /// <param name="type"></param>
-        /// <param name="sourceLineNumbers"></param>
-        /// <param name="bindStage"></param>
-        /// <returns></returns>
-        public virtual IResolveFileResult ResolveRelatedFile(string source, string relatedSource, string type, SourceLineNumber sourceLineNumbers, BindStage bindStage)
+        public virtual IResolveFileResult ResolveRelatedFile(string source, string relatedSource, string type, SourceLineNumber sourceLineNumbers)
         {
             return null;
         }
 
         /// <summary>
-        /// 
+        /// See <see cref="IBurnBackendExtension.SymbolsFinalized(IntermediateSection)"/>
+        /// </summary>
+        public virtual void SymbolsFinalized(IntermediateSection section)
+        {
+        }
+
+        /// <summary>
+        /// See <see cref="IBurnBackendExtension.ResolveUrl(String, String, String, String, String)"/>
         /// </summary>
-        /// <param name="url"></param>
-        /// <param name="fallbackUrl"></param>
-        /// <param name="packageId"></param>
-        /// <param name="payloadId"></param>
-        /// <param name="fileName"></param>
-        /// <returns></returns>
         public virtual string ResolveUrl(string url, string fallbackUrl, string packageId, string payloadId, string fileName)
         {
             return null;
         }
 
         /// <summary>
-        /// Called for each extension symbol that hasn't been handled yet.
-        /// Use IBurnBackendHelper to add data to the appropriate data manifest.
+        /// See <see cref="IBurnBackendExtension.TryProcessSymbol(IntermediateSection, IntermediateSymbol)"/>
         /// </summary>
-        /// <param name="section">The linked section.</param>
-        /// <param name="symbol">The current symbol.</param>
-        /// <returns>
-        /// True if the extension handled the symbol, false otherwise.
-        /// The Burn backend will warn on all unhandled symbols.
-        /// </returns>
-        public virtual bool TryAddSymbolToDataManifest(IntermediateSection section, IntermediateSymbol symbol)
+        public virtual bool TryProcessSymbol(IntermediateSection section, IntermediateSymbol symbol)
         {
             if (this.SymbolDefinitions.Any(t => t == symbol.Definition) &&
                 symbol.Definition.HasTag(BurnConstants.BootstrapperApplicationDataSymbolDefinitionTag))
@@ -109,5 +82,13 @@ namespace WixToolset.Extensibility
 
             return false;
         }
+
+        /// <summary>
+        /// See <see cref="IBurnBackendExtension.PostBackendBind(IBindResult)"/>
+        /// </summary>
+        /// <param name="result"></param>
+        public virtual void PostBackendBind(IBindResult result)
+        {
+        }
     }
 }
diff --git a/src/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs b/src/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs
index c0086aed..47777fae 100644
--- a/src/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs
+++ b/src/WixToolset.Extensibility/BaseWindowsInstallerBackendBinderExtension.cs
@@ -53,9 +53,9 @@ namespace WixToolset.Extensibility
         }
 
         /// <summary>
-        /// See <see cref="IWindowsInstallerBackendBinderExtension.FullyResolved(IntermediateSection)"/>
+        /// See <see cref="IWindowsInstallerBackendBinderExtension.SymbolsFinalized(IntermediateSection)"/>
         /// </summary>
-        public virtual void FullyResolved(IntermediateSection section)
+        public virtual void SymbolsFinalized(IntermediateSection section)
         {
         }
 
@@ -70,13 +70,13 @@ namespace WixToolset.Extensibility
         public virtual string ResolveMedia(MediaSymbol mediaRow, string mediaLayoutDirectory, string layoutDirectory) => null;
 
         /// <summary>
-        /// See <see cref="IWindowsInstallerBackendBinderExtension.PreBackendBind(IBindContext)"/>
+        /// See <see cref="IWindowsInstallerBackendBinderExtension.TryProcessSymbol(IntermediateSection, IntermediateSymbol, WindowsInstallerData, TableDefinitionCollection)"/>
         /// </summary>
-        public virtual bool TryAddSymbolToOutput(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData output, TableDefinitionCollection tableDefinitions)
+        public virtual bool TryProcessSymbol(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData data, TableDefinitionCollection tableDefinitions)
         {
             if (this.TableDefinitions.Any(t => t.SymbolDefinition == symbol.Definition))
             {
-                return this.BackendHelper.TryAddSymbolToOutputMatchingTableDefinitions(section, symbol, output, tableDefinitions);
+                return this.BackendHelper.TryAddSymbolToOutputMatchingTableDefinitions(section, symbol, data, tableDefinitions);
             }
 
             return false;
diff --git a/src/WixToolset.Extensibility/IBurnBackendExtension.cs b/src/WixToolset.Extensibility/IBurnBackendExtension.cs
index 769c2457..07f5cd1b 100644
--- a/src/WixToolset.Extensibility/IBurnBackendExtension.cs
+++ b/src/WixToolset.Extensibility/IBurnBackendExtension.cs
@@ -16,30 +16,36 @@ namespace WixToolset.Extensibility
         void PreBackendBind(IBindContext context);
 
         /// <summary>
-        /// 
+        /// Called to find a file related to another source in the authoring. For example, most often used
+        /// to find cabinets and uncompressed files for an MSI package.
         /// </summary>
-        /// <param name="source"></param>
-        /// <param name="relatedSource"></param>
-        /// <param name="type"></param>
-        /// <param name="sourceLineNumbers"></param>
-        /// <param name="bindStage"></param>
-        /// <returns></returns>
-        IResolveFileResult ResolveRelatedFile(string source, string relatedSource, string type, SourceLineNumber sourceLineNumbers, BindStage bindStage);
+        /// <param name="source">Path to the source package.</param>
+        /// <param name="relatedSource">Expected path to the related file.</param>
+        /// <param name="type">Type of related file, such as "File" or "Cabinet"</param>
+        /// <param name="sourceLineNumbers">Source line number of source package.</param>
+        /// <returns><c>IResolveFileResult</c> if the related file was found, or null for default handling.</returns>
+        IResolveFileResult ResolveRelatedFile(string source, string relatedSource, string type, SourceLineNumber sourceLineNumbers);
 
         /// <summary>
-        /// 
+        /// Called right before the output is bound into its final format.
         /// </summary>
-        /// <param name="url"></param>
-        /// <param name="fallbackUrl"></param>
-        /// <param name="packageId"></param>
-        /// <param name="payloadId"></param>
-        /// <param name="fileName"></param>
-        /// <returns></returns>
+        /// <param name="section">The finalized intermediate section.</param>
+        void SymbolsFinalized(IntermediateSection section);
+
+        /// <summary>
+        /// Called to customize the DownloadUrl provided in source cde.
+        /// </summary>
+        /// <param name="url">The value from the source code. May not actually be a URL.</param>
+        /// <param name="fallbackUrl">The default URL if the extension does not return a value.</param>
+        /// <param name="packageId">Identifier of the package.</param>
+        /// <param name="payloadId">Identifier of the payload.</param>
+        /// <param name="fileName">Filename of the payload.</param>
+        /// <returns>Url to override, or null to use default value.</returns>
         string ResolveUrl(string url, string fallbackUrl, string packageId, string payloadId, string fileName);
 
         /// <summary>
         /// Called for each extension symbol that hasn't been handled yet.
-        /// Use IBurnBackendHelper to add data to the appropriate data manifest.
+        /// Use IBurnBackendHelper to add data.
         /// </summary>
         /// <param name="section">The linked section.</param>
         /// <param name="symbol">The current symbol.</param>
@@ -47,12 +53,7 @@ namespace WixToolset.Extensibility
         /// True if the extension handled the symbol, false otherwise.
         /// The Burn backend will warn on all unhandled symbols.
         /// </returns>
-        bool TryAddSymbolToDataManifest(IntermediateSection section, IntermediateSymbol symbol);
-
-        /// <summary>
-        /// Called after all output changes occur and right before the output is bound into its final format.
-        /// </summary>
-        void BundleFinalize();
+        bool TryProcessSymbol(IntermediateSection section, IntermediateSymbol symbol);
 
         /// <summary>
         /// Called after output is bound into its final format.
diff --git a/src/WixToolset.Extensibility/IWindowsInstallerBackendBinderExtension.cs b/src/WixToolset.Extensibility/IWindowsInstallerBackendBinderExtension.cs
index b913dadc..12a38b9a 100644
--- a/src/WixToolset.Extensibility/IWindowsInstallerBackendBinderExtension.cs
+++ b/src/WixToolset.Extensibility/IWindowsInstallerBackendBinderExtension.cs
@@ -24,10 +24,10 @@ namespace WixToolset.Extensibility
         void PreBackendBind(IBindContext context);
 
         /// <summary>
-        /// 
+        /// Extension can process the intermediate before the Windows Installer data is created.
         /// </summary>
-        /// <param name="section">The resolved intermedate section.</param>
-        void FullyResolved(IntermediateSection section);
+        /// <param name="section">The finalized intermediate section.</param>
+        void SymbolsFinalized(IntermediateSection section);
 
         /// <summary>
         /// Finds an existing cabinet that contains the provided files.
@@ -41,20 +41,20 @@ namespace WixToolset.Extensibility
         /// Override layout location for a media.
         /// </summary>
         /// <param name="mediaSymbol">Media symbol.</param>
-        /// <param name="mediaLayoutDirectory">Default media layout directory.</param>
-        /// <param name="layoutDirectory">Default layout directory.</param>
+        /// <param name="mediaLayoutDirectory">Default media specific layout directory.</param>
+        /// <param name="layoutDirectory">Default overall layout directory.</param>
         /// <returns>Layout location or null to use the default processing.</returns>
         string ResolveMedia(MediaSymbol mediaSymbol, string mediaLayoutDirectory, string layoutDirectory);
 
         /// <summary>
-        /// 
+        /// Called for each extension symbol that hasn't been handled yet.
         /// </summary>
-        /// <param name="section"></param>
-        /// <param name="symbol"></param>
-        /// <param name="output">Windows Installer data </param>
+        /// <param name="section">The linked section.</param>
+        /// <param name="symbol">The current symbol.</param>
+        /// <param name="data">Windows Installer data </param>
         /// <param name="tableDefinitions">Collection of table definitions available for the output.</param>
-        /// <returns>True if the symbol was added to the output, or false if not.</returns>
-        bool TryAddSymbolToOutput(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData output, TableDefinitionCollection tableDefinitions);
+        /// <returns>True if the symbol was handled, or false if not.</returns>
+        bool TryProcessSymbol(IntermediateSection section, IntermediateSymbol symbol, WindowsInstallerData data, TableDefinitionCollection tableDefinitions);
 
         /// <summary>
         /// Called after all output changes occur and right before the output is bound into its final format.