More initial reviews of [u*-v*] interface headers.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53303 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/url.h

@@ -6,17 +6,29 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    Error types returned from wxURL::GetError().
+*/
+typedef enum {
+    wxURL_NOERR = 0,    ///< No error.
+    wxURL_SNTXERR,      ///< Syntax error in the URL string.
+    wxURL_NOPROTO,      ///< Found no protocol which can get this URL.
+    wxURL_NOHOST,       ///< A host name is required for this protocol.
+    wxURL_NOPATH,       ///< A path is required for this protocol.
+    wxURL_CONNERR,      ///< Connection error.
+    wxURL_PROTOERR      ///< An error occurred during negotiation.
+} wxURLError;
+
 /**
     @class wxURL
     @wxheader{url.h}
 
-    wxURL is a specialization of wxURI for parsing URLs.
-    Please look at wxURI documentation for more info about the functions
-    you can use to retrieve the various parts of the URL (scheme, server, port,
-    etc).
+    wxURL is a specialization of wxURI for parsing URLs. Please look at wxURI
+    documentation for more info about the functions you can use to retrieve the
+    various parts of the URL (scheme, server, port, etc).
 
-    Supports standard assignment operators, copy constructors,
-    and comparison operators.
+    Supports standard assignment operators, copy constructors, and comparison
+    operators.
 
     @library{wxnet}
     @category{net}
@@ -27,13 +39,14 @@ class wxURL : public wxURI
 {
 public:
     /**
-        Constructs a URL object from the string.  The URL must be valid according
-        to RFC 1738.  In particular, file URLs must be of the format
-        @c file://hostname/path/to/file otherwise GetError()
-        will return a value different from @c wxURL_NOERR.
-        It is valid to leave out the hostname but slashes must remain in place -
-        i.e. a file URL without a hostname must contain three consecutive slashes
-        (e.g. @c file:///somepath/myfile).
+        Constructs a URL object from the string. The URL must be valid
+        according to RFC 1738. In particular, file URLs must be of the format
+        @c "file://hostname/path/to/file", otherwise GetError() will return a
+        value different from ::wxURL_NOERR.
+
+        It is valid to leave out the hostname but slashes must remain in place,
+        in other words, a file URL without a hostname must contain three
+        consecutive slashes (e.g. @c "file:///somepath/myfile").
 
         @param url
             Url string to parse.
@@ -46,47 +59,32 @@ public:
     ~wxURL();
 
     /**
-        Returns the last error. This error refers to the URL parsing or to the protocol.
-        It can be one of these errors:
-
-        @b wxURL_NOERR
-
-        No error.
-
-        @b wxURL_SNTXERR
-
-        Syntax error in the URL string.
-
-        @b wxURL_NOPROTO
-
-        Found no protocol which can get this URL.
-
-        @b wxURL_NOHOST
-
-        A host name is required for this protocol.
-
-        @b wxURL_NOPATH
-
-        A path is required for this protocol.
-
-        @b wxURL_CONNERR
-
-        Connection error.
-
-        @b wxURL_PROTOERR
-
-        An error occurred during negotiation.
+        Returns the last error. This error refers to the URL parsing or to the
+        protocol. It can be one of ::wxURLError.
     */
     wxURLError GetError() const;
 
     /**
-        Creates a new input stream on the specified URL. You can use all but seek
-        functionality of wxStream. Seek isn't available on all streams. For example,
-        HTTP or FTP streams don't deal with it.
-        Note that this method is somewhat deprecated, all future wxWidgets applications
-        should really use wxFileSystem instead.
+        Creates a new input stream on the specified URL. You can use all but
+        seek functionality of wxStream. Seek isn't available on all streams.
+        For example, HTTP or FTP streams don't deal with it.
+
+        Note that this method is somewhat deprecated, all future wxWidgets
+        applications should use wxFileSystem instead.
+
         Example:
 
+        @code
+        wxURL url("http://a.host/a.dir/a.file");
+        if (url.GetError() == wxURL_NOERR)
+        {
+            wxInputStream *in_stream;
+
+            in_stream = url.GetInputStream();
+            // Then, you can use all IO calls of in_stream (See wxStream)
+        }
+        @endcode
+
         @returns Returns the initialized stream. You will have to delete it
                  yourself.
 
@@ -101,16 +99,16 @@ public:
 
     /**
         Returns @true if this object is correctly initialized, i.e. if
-        GetError() returns @c wxURL_NOERR.
+        GetError() returns ::wxURL_NOERR.
     */
     bool IsOk() const;
 
     /**
-        Sets the default proxy server to use to get the URL. The string specifies
-        the proxy like this: hostname:port number.
+        Sets the default proxy server to use to get the URL. The string
+        specifies the proxy like this: @c "<hostname>:<port number>".
 
         @param url_proxy
-            Specifies the proxy to use
+            Specifies the proxy to use.
 
         @see SetProxy()
     */
@@ -124,8 +122,8 @@ public:
     void SetProxy(const wxString& url_proxy);
 
     /**
-        Initializes this object with the given URL and returns @c wxURL_NOERR
-        if it's valid (see GetError() for more info).
+        Initializes this object with the given URL and returns ::wxURL_NOERR if
+        it's valid (see GetError() for more info).
     */
     wxURLError SetURL(const wxString& url);
 };