Xml Doc - Improvements and fixes

- Some classes are now excluded
- Many minor fixes should hopefully reduce the number of errors reported by Sandcastle
- Some of the xml doc is generated by Atomineer, usually in cases where CEF lacks documentation

Author: amaitland

CefSharp.Core/AbstractCefSettings.h

@@ -48,6 +48,9 @@ namespace CefSharp
             _ownsPointer = true;
         }
 
+        /// <summary>
+        /// Finalizer.
+        /// </summary>
         !BrowserSettings()
         {
             if (_ownsPointer)
@@ -59,6 +62,9 @@ namespace CefSharp
             _isDisposed = true;
         }
 
+        /// <summary>
+        /// Destructor.
+        /// </summary>
         ~BrowserSettings()
         {
             this->!BrowserSettings();
@@ -392,6 +398,9 @@ namespace CefSharp
             bool get() { return _isDisposed; }
         }
 
+        /// <summary>
+        /// True if framework created.
+        /// </summary>
         virtual property bool FrameworkCreated
         {
             bool get() { return _frameworkCreated; }

CefSharp.Core/BrowserSettings.h

@@ -33,6 +33,11 @@ using namespace msclr::interop;
 
 namespace CefSharp
 {
+    /// <summary>
+    /// Global CEF methods are exposed through this class. e.g. CefInitalize maps to Cef.Initialize
+    /// CEF API Doc https://magpcss.org/ceforum/apidocs3/projects/(default)/(_globals).html
+    /// This class cannot be inherited.
+    /// </summary>
     public ref class Cef sealed
     {
     private:
@@ -688,7 +693,7 @@ namespace CefSharp
         /// The client application is responsible for downloading an appropriate
         /// platform-specific CDM binary distribution from Google, extracting the
         /// contents, and building the required directory structure on the local machine.
-        /// The <see cref="CefSharp.IBrowserHost.StartDownload"/> method class can be used
+        /// The <see cref="CefSharp::IBrowserHost::StartDownload"/> method class can be used
         /// to implement this functionality in CefSharp. Contact Google via
         /// https://www.widevine.com/contact.html for details on CDM download.
         /// 
@@ -702,7 +707,7 @@ namespace CefSharp
         ///
         /// If any of these files are missing or if the manifest file has incorrect
         /// contents the registration will fail and callback will receive an ErrorCode
-        /// value of <see cref="CefSharp.CdmRegistrationErrorCode.IncorrectContents"/>.
+        /// value of <see cref="CefSharp::CdmRegistrationErrorCode::IncorrectContents"/>.
         ///
         /// The manifest.json file must contain the following keys:
         ///   A. "os": Supported OS (e.g. "mac", "win" or "linux").
@@ -715,13 +720,13 @@ namespace CefSharp
         ///
         /// A through E are used to verify compatibility with the current Chromium
         /// version. If the CDM is not compatible the registration will fail and
-        /// callback will receive an ErrorCode value of <see cref="CdmRegistrationErrorCode.Incompatible"/>.
+        /// callback will receive an ErrorCode value of <see cref="CdmRegistrationErrorCode::Incompatible"/>.
         ///
         /// If registration is not supported at the time that Cef.RegisterWidevineCdm() is called then callback
-        /// will receive an ErrorCode value of <see cref="CdmRegistrationErrorCode.NotSupported"/>.
+        /// will receive an ErrorCode value of <see cref="CdmRegistrationErrorCode::NotSupported"/>.
         /// </summary>
         /// <param name="path"> is a directory that contains the Widevine CDM files</param>
-        /// <param name="callback">optional callback - <see cref="IRegisterCdmCallback.OnRegistrationCompletecallback"/> 
+        /// <param name="callback">optional callback - <see cref="IRegisterCdmCallback::OnRegistrationCompletecallback"/> 
         /// will be executed asynchronously once registration is complete</param>
         static void RegisterWidevineCdm(String^ path, [Optional] IRegisterCdmCallback^ callback)
         {

CefSharp.Core/Cef.h

@@ -11,6 +11,7 @@
 
 namespace CefSharp
 {
+    /// <exclude />
     public ref class CookieManager : public ICookieManager
     {
     private:

CefSharp.Core/CookieManager.h

@@ -26,6 +26,7 @@ using namespace CefSharp::ModelBinding;
 
 namespace CefSharp
 {
+    /// <exclude />
     public ref class ManagedCefBrowserAdapter : public IBrowserAdapter
     {
         MCefRefPtr<ClientAdapter> _clientAdapter;

CefSharp.Core/ManagedCefBrowserAdapter.h

@@ -8,6 +8,7 @@
 
 namespace CefSharp
 {
+    /// <exclude />
     public ref class NativeMethodWrapper sealed
     {
     public:

CefSharp.Core/NativeMethodWrapper.h

@@ -11,12 +11,17 @@ namespace CefSharp
     /// <summary>
     /// Class representing popup window features.
     /// </summary>
+    /// <exclude />
     public ref class PopupFeatures : IPopupFeatures
     {
     private:
         const CefPopupFeatures* _popupFeatures;
 
     public:
+        /// <summary>
+        /// Constructor.
+        /// </summary>
+        /// <param name="popupFeatures">The popup features.</param>
         PopupFeatures(const CefPopupFeatures* popupFeatures)
         {
             _popupFeatures = popupFeatures;
@@ -98,4 +103,4 @@ namespace CefSharp
             void set(List<String^>^ value) { _popupFeatures->dialog = value; }
         }*/
     };
-}
+}

CefSharp.Core/PopupFeatures.h

@@ -17,6 +17,10 @@ using namespace System::Collections::ObjectModel;
 
 namespace CefSharp
 {
+    /// <summary>
+    /// Form Post Data
+    /// </summary>
+    /// <seealso cref="T:IPostData"/>
     public ref class PostData : public IPostData, public CefWrapper
     {
         MCefRefPtr<CefPostData> _postData;
@@ -29,11 +33,17 @@ namespace CefSharp
 
         }
 
+        /// <summary>
+        /// Finalizer.
+        /// </summary>
         !PostData()
         {
             _postData = nullptr;
         }
 
+        /// <summary>
+        /// Destructor.
+        /// </summary>
         ~PostData()
         {
             this->!PostData();
@@ -52,12 +62,30 @@ namespace CefSharp
             _disposed = true;
         }
 
+        /// <summary>
+        /// Throw exception if Readonly
+        /// </summary>
+        /// <exception cref="Exception">Thrown when an exception error condition occurs.</exception>
+        void ThrowIfReadOnly()
+        {
+            if (IsReadOnly)
+            {
+                throw gcnew Exception(gcnew String(L"This IPostDataWrapper is readonly and cannot be modified."));
+            }
+        }
+
     public:
+        /// <summary>
+        /// Default constructor.
+        /// </summary>
         PostData()
         {
             _postData = CefPostData::Create();
         }
 
+        /// <summary>
+        /// Returns true if this object is read-only.
+        /// </summary>
         virtual property bool IsReadOnly
         {
             bool get()
@@ -68,6 +96,9 @@ namespace CefSharp
             }
         }
 
+        /// <summary>
+        /// Retrieve the post data elements.
+        /// </summary>
         virtual property IList<IPostDataElement^>^ Elements
         {
             IList<IPostDataElement^>^ get()
@@ -99,6 +130,11 @@ namespace CefSharp
             }
         }
 
+        /// <summary>
+        /// Add the specified <see cref="IPostDataElement"/>.
+        /// </summary>
+        /// <param name="element">element to be added.</param>
+        /// <returns>Returns true if the add succeeds.</returns>
         virtual bool AddElement(IPostDataElement^ element)
         {
             ThrowIfDisposed();
@@ -121,6 +157,11 @@ namespace CefSharp
             return _postData->AddElement(elementWrapper);
         }
 
+        /// <summary>
+        /// Remove  the specified <see cref="IPostDataElement"/>.
+        /// </summary>
+        /// <param name="element">element to be removed.</param>
+        /// <returns> Returns true if the add succeeds.</returns>
         virtual bool RemoveElement(IPostDataElement^ element)
         {
             ThrowIfDisposed();
@@ -142,6 +183,9 @@ namespace CefSharp
             return _postData->RemoveElement(elementWrapper);
         }
 
+        /// <summary>
+        /// Remove all existing post data elements.
+        /// </summary>
         virtual void RemoveElements()
         {
             ThrowIfDisposed();
@@ -151,13 +195,23 @@ namespace CefSharp
             _postData->RemoveElements();
         }
 
+        /// <summary>
+        /// Create a new <see cref="IPostDataElement"/> instance
+        /// </summary>
+        /// <returns>PostDataElement</returns>
         virtual IPostDataElement^ CreatePostDataElement()
         {
             auto element = CefPostDataElement::Create();
 
             return gcnew PostDataElement(element);
         }
 
+        /// <summary>
+        /// Returns true if the underlying POST data includes elements that are not
+        /// represented by this IPostData object (for example, multi-part file upload
+        /// data). Modifying IPostData objects with excluded elements may result in
+        /// the request failing.
+        /// </summary>
         virtual property bool HasExcludedElements
         {
             bool get()
@@ -168,14 +222,6 @@ namespace CefSharp
             }
         }
 
-        void ThrowIfReadOnly()
-        {
-            if (IsReadOnly)
-            {
-                throw gcnew Exception(gcnew String(L"This IPostDataWrapper is readonly and cannot be modified."));
-            }
-        }
-
         operator CefRefPtr<CefPostData>()
         {
             if (this == nullptr)

CefSharp.Core/PostData.h

@@ -27,6 +27,7 @@ public interface IJavascriptCallback : IDisposable
         /// <summary>
         /// Execute the javascript callback
         /// </summary>
+        /// <param name="timeout">timeout</param>
         /// <param name="parms">param array of objects</param>
         /// <returns>JavascriptResponse</returns>
         Task<JavascriptResponse> ExecuteWithTimeoutAsync(TimeSpan? timeout, params object[] parms);

CefSharp/Callback/IJavascriptCallback.cs

@@ -7,17 +7,17 @@
 namespace CefSharp.Callback
 {
     /// <summary>
-    /// Callback for asynchronous continuation of <see cref="IResourceHandler.Read(System.IO.Stream, int, out int, IResourceReadCallback)"/>.
+    /// Callback for asynchronous continuation of <see cref="IResourceHandler.Read"/>.
     /// </summary>
     public interface IResourceReadCallback : IDisposable
     {
         /// <summary>
-        /// Callback for asynchronous continuation of <see cref="IResourceHandler.Read(System.IO.Stream, int, out int, IResourceReadCallback)"/>. If bytesRead == 0
+        /// Callback for asynchronous continuation of <see cref="IResourceHandler.Read"/>. If bytesRead == 0
         /// the response will be considered complete. 
         /// </summary>
         /// <param name="bytesRead">
         /// If bytesRead == 0 the response will be considered complete.
-        /// If bytesRead &gt; 0 then <see cref="IResourceHandler.Read(System.IO.Stream, int, out int, IResourceReadCallback)"/> will be called again until the request is complete (based on either the
+        /// If bytesRead &gt; 0 then <see cref="IResourceHandler.Read"/> will be called again until the request is complete (based on either the
         /// result or the expected content length). If bytesRead &lt; 0 then the
         /// request will fail and the bytesRead value will be treated as the error
         /// code.