From 83bf1f8608af56e8f990cb225b1abe69ee42bc86 Mon Sep 17 00:00:00 2001 From: sta Date: Wed, 23 Apr 2014 21:13:36 +0900 Subject: [PATCH] Fix some xml doc comments for HttpListener.cs --- websocket-sharp/Net/HttpListener.cs | 197 ++++++++++++---------------- 1 file changed, 87 insertions(+), 110 deletions(-) diff --git a/websocket-sharp/Net/HttpListener.cs b/websocket-sharp/Net/HttpListener.cs index 350ef53a..9b4312cc 100644 --- a/websocket-sharp/Net/HttpListener.cs +++ b/websocket-sharp/Net/HttpListener.cs @@ -33,7 +33,7 @@ #region Authors /* * Authors: - * Gonzalo Paniagua Javier + * - Gonzalo Paniagua Javier */ #endregion @@ -44,7 +44,7 @@ using System.Security.Cryptography.X509Certificates; using System.Security.Principal; using System.Threading; -// TODO: logging +// TODO: Logging. namespace WebSocketSharp.Net { /// @@ -104,12 +104,12 @@ namespace WebSocketSharp.Net /// Gets or sets the scheme used to authenticate the clients. /// /// - /// One of the values - /// that indicates the scheme used to authenticate the clients. The default - /// value is . + /// One of the enum values, + /// represents the scheme used to authenticate the clients. The default value is + /// . /// /// - /// This object has been closed. + /// This listener has been closed. /// public AuthenticationSchemes AuthenticationSchemes { get { @@ -124,16 +124,14 @@ namespace WebSocketSharp.Net } /// - /// Gets or sets the delegate called to determine the scheme used to - /// authenticate clients. + /// Gets or sets the delegate called to determine the scheme used to authenticate clients. /// /// - /// A delegate that invokes the - /// method(s) used to select an authentication scheme. The default value is - /// . + /// A delegate that invokes the method(s) used to + /// select an authentication scheme. The default value is . /// /// - /// This object has been closed. + /// This listener has been closed. /// public AuthenticationSchemeSelector AuthenticationSchemeSelectorDelegate { get { @@ -148,29 +146,29 @@ namespace WebSocketSharp.Net } /// - /// Gets or sets the path to the folder stored the certificate files used to + /// Gets or sets the path to the folder in which stores the certificate files used to /// authenticate the server on the secure connection. /// /// - /// This property represents the path to the folder stored the certificate - /// files associated with the port number of each added URI prefix. A set of - /// the certificate files is a pair of the 'port number'.cer (DER) and - /// 'port number'.key (DER, RSA Private Key). + /// This property represents the path to the folder in which stores the certificate files + /// associated with each port number of added URI prefixes. A set of the certificate files + /// is a pair of the 'port number'.cer (DER) and 'port number'.key + /// (DER, RSA Private Key). /// /// - /// A that contains the path to the certificate folder. - /// The default value is the result of Environment.GetFolderPath - /// (). + /// A that represents the path to the folder in which stores the + /// certificate files. The default value is result of System.Environment.GetFolderPath + /// (). /// /// - /// This object has been closed. + /// This listener has been closed. /// public string CertificateFolderPath { get { CheckDisposed (); return _certFolderPath == null || _certFolderPath.Length == 0 - ? (_certFolderPath = Environment.GetFolderPath ( - Environment.SpecialFolder.ApplicationData)) + ? (_certFolderPath = + Environment.GetFolderPath (Environment.SpecialFolder.ApplicationData)) : _certFolderPath; } @@ -181,16 +179,16 @@ namespace WebSocketSharp.Net } /// - /// Gets or sets the default certificate used to authenticate the server on - /// the secure connection. + /// Gets or sets the default certificate used to authenticate the server on the secure + /// connection. /// /// - /// A used to authenticate the server if the - /// certificate associated with the port number of each added URI prefix is - /// not found in the . + /// A used to authenticate the server if the certificate + /// files aren't found in the . The default value is + /// . /// /// - /// This object has been closed. + /// This listener has been closed. /// public X509Certificate2 DefaultCertificate { get { @@ -205,16 +203,15 @@ namespace WebSocketSharp.Net } /// - /// Gets or sets a value indicating whether the - /// returns exceptions that occur when sending the response to the client. + /// Gets or sets a value indicating whether the listener returns exceptions that occur when + /// sending the response to the client. /// /// - /// true if the doesn't return exceptions - /// that occur when sending the response to the client; otherwise, - /// false. The default value is false. + /// true if the listener doesn't return exceptions that occur when sending the response + /// to the client; otherwise, false. The default value is false. /// /// - /// This object has been closed. + /// This listener has been closed. /// public bool IgnoreWriteExceptions { get { @@ -229,12 +226,10 @@ namespace WebSocketSharp.Net } /// - /// Gets a value indicating whether the has been - /// started. + /// Gets a value indicating whether the listener has been started. /// /// - /// true if the has been started; otherwise, - /// false. + /// true if the listener has been started; otherwise, false. /// public bool IsListening { get { @@ -243,8 +238,7 @@ namespace WebSocketSharp.Net } /// - /// Gets a value indicating whether the can be - /// used with the current operating system. + /// Gets a value indicating whether the listener can be used with the current operating system. /// /// /// true. @@ -256,14 +250,13 @@ namespace WebSocketSharp.Net } /// - /// Gets the URI prefixes handled by the . + /// Gets the URI prefixes handled by the listener. /// /// - /// A that contains the URI - /// prefixes. + /// A that contains the URI prefixes. /// /// - /// This object has been closed. + /// This listener has been closed. /// public HttpListenerPrefixCollection Prefixes { get { @@ -273,15 +266,14 @@ namespace WebSocketSharp.Net } /// - /// Gets or sets the name of the realm associated with the - /// . + /// Gets or sets the name of the realm associated with the listener. /// /// - /// A that contains the name of the realm. The default - /// value is SECRET AREA. + /// A that represents the name of the realm. The default value is + /// SECRET AREA. /// /// - /// This object has been closed. + /// This listener has been closed. /// public string Realm { get { @@ -324,16 +316,16 @@ namespace WebSocketSharp.Net } /// - /// Gets or sets the delegate called to find the credentials for an identity - /// used to authenticate a client. + /// Gets or sets the delegate called to find the credentials for an identity used to + /// authenticate a client. /// /// - /// A Func<, > - /// delegate that references the method(s) used to find the credentials. The - /// default value is a function that only returns . + /// A Func<, > delegate + /// that invokes the method(s) used to find the credentials. The default value is a function + /// that only returns . /// /// - /// This object has been closed. + /// This listener has been closed. /// public Func UserCredentialsFinder { get { @@ -369,7 +361,7 @@ namespace WebSocketSharp.Net if (_connections.Count == 0) return; - // Need to copy this since closing will call RemoveConnection + // Need to copy this since closing will call RemoveConnection. var keys = _connections.Keys; var conns = new HttpConnection [keys.Count]; keys.CopyTo (conns, 0); @@ -385,7 +377,7 @@ namespace WebSocketSharp.Net if (_registry.Count == 0) return; - // Need to copy this since closing will call UnregisterContext + // Need to copy this since closing will call UnregisterContext. var keys = _registry.Keys; var all = new HttpListenerContext [keys.Count]; keys.CopyTo (all, 0); @@ -402,9 +394,8 @@ namespace WebSocketSharp.Net return; var ex = new ObjectDisposedException (GetType ().ToString ()); - foreach (var ares in _waitQueue) { + foreach (var ares in _waitQueue) ares.Complete (ex); - } _waitQueue.Clear (); } @@ -416,7 +407,7 @@ namespace WebSocketSharp.Net cleanup (force); } - // Must be called with a lock on _contextQueue + // Must be called with a lock on _contextQueue. private HttpListenerContext getContextFromQueue () { if (_contextQueue.Count == 0) @@ -457,14 +448,12 @@ namespace WebSocketSharp.Net { CheckDisposed (); if (_prefixes.Count == 0) - throw new InvalidOperationException ( - "Please, call AddPrefix before using this method."); + throw new InvalidOperationException ("Please, call AddPrefix before using this method."); if (!_listening) - throw new InvalidOperationException ( - "Please, call Start before using this method."); + throw new InvalidOperationException ("Please, call Start before using this method."); - // Lock _waitQueue early to avoid race conditions + // Lock _waitQueue early to avoid race conditions. lock (((ICollection) _waitQueue).SyncRoot) { lock (((ICollection) _contextQueue).SyncRoot) { var context = getContextFromQueue (); @@ -512,8 +501,7 @@ namespace WebSocketSharp.Net _connections.Remove (connection); } - internal AuthenticationSchemes SelectAuthenticationScheme ( - HttpListenerContext context) + internal AuthenticationSchemes SelectAuthenticationScheme (HttpListenerContext context) { return AuthenticationSchemeSelectorDelegate != null ? AuthenticationSchemeSelectorDelegate (context.Request) @@ -537,7 +525,7 @@ namespace WebSocketSharp.Net #region Public Methods /// - /// Shuts down the immediately. + /// Shuts down the listener immediately. /// public void Abort () { @@ -552,17 +540,15 @@ namespace WebSocketSharp.Net /// Begins getting an incoming request information asynchronously. /// /// - /// This asynchronous operation must be completed by calling the - /// EndGetContext method. Typically, that method is invoked by the - /// delegate. + /// This asynchronous operation must be completed by calling the EndGetContext method. + /// Typically, that method is invoked by the delegate. /// /// - /// An that contains the status of the - /// asynchronous operation. + /// An that represents the status of the asynchronous operation. /// /// - /// An delegate that references the method(s) - /// called when the asynchronous operation completes. + /// An delegate that references the method(s) to invoke + /// when the asynchronous operation completes. /// /// /// An that contains a user defined object to pass to @@ -570,19 +556,17 @@ namespace WebSocketSharp.Net /// /// /// - /// The does not have any URI prefixes to listen - /// on. + /// This listener doesn't have any URI prefixes to listen on. /// /// /// -or- /// /// - /// The has not been started or is stopped - /// currently. + /// This listener hasn't been started or is stopped currently. /// /// /// - /// This object has been closed. + /// This listener has been closed. /// public IAsyncResult BeginGetContext (AsyncCallback callback, Object state) { @@ -590,7 +574,7 @@ namespace WebSocketSharp.Net } /// - /// Shuts down the . + /// Shuts down the listener. /// public void Close () { @@ -605,30 +589,26 @@ namespace WebSocketSharp.Net /// Ends an asynchronous operation to get an incoming request information. /// /// - /// This method completes an asynchronous operation started by calling the - /// BeginGetContext method. + /// This method completes an asynchronous operation started by calling + /// the BeginGetContext method. /// /// - /// A that contains a client's request - /// information. + /// A that contains a request information. /// /// - /// An obtained by calling the - /// BeginGetContext method. + /// An obtained by calling the BeginGetContext method. /// - /// - /// was not obtained by calling the - /// BeginGetContext method. - /// /// /// is . /// + /// + /// wasn't obtained by calling the BeginGetContext method. + /// /// - /// This method was already called for the specified - /// . + /// This method was already called for the specified . /// /// - /// This object has been closed. + /// This listener has been closed. /// public HttpListenerContext EndGetContext (IAsyncResult asyncResult) { @@ -654,9 +634,9 @@ namespace WebSocketSharp.Net } var context = ares.GetContext (); - var authScheme = SelectAuthenticationScheme (context); - if (authScheme != AuthenticationSchemes.Anonymous) - context.SetUser (authScheme, Realm, UserCredentialsFinder); + var scheme = SelectAuthenticationScheme (context); + if (scheme != AuthenticationSchemes.Anonymous) + context.SetUser (scheme, Realm, UserCredentialsFinder); return context; // This will throw on error. } @@ -665,28 +645,25 @@ namespace WebSocketSharp.Net /// Gets an incoming request information. /// /// - /// This method waits for an incoming request and returns the request - /// information when received the request. + /// This method waits for an incoming request and returns a request information + /// when the listener receives a request. /// /// - /// A that contains a client's request - /// information. + /// A that contains a request information. /// /// /// - /// The does not have any URI prefixes to listen - /// on. + /// This listener doesn't have any URI prefixes to listen on. /// /// /// -or- /// /// - /// The has not been started or is stopped - /// currently. + /// This listener hasn't been started or is stopped currently. /// /// /// - /// This object has been closed. + /// This listener has been closed. /// public HttpListenerContext GetContext () { @@ -700,7 +677,7 @@ namespace WebSocketSharp.Net /// Starts to receive incoming requests. /// /// - /// This object has been closed. + /// This listener has been closed. /// public void Start () { @@ -716,7 +693,7 @@ namespace WebSocketSharp.Net /// Stops receiving incoming requests. /// /// - /// This object has been closed. + /// This listener has been closed. /// public void Stop () { @@ -734,7 +711,7 @@ namespace WebSocketSharp.Net #region Explicit Interface Implementation /// - /// Releases all resource used by the . + /// Releases all resource used by the listener. /// void IDisposable.Dispose () {