docs: various small fixes

[platform/upstream/glib.git] / gio / gtlscertificate.c

diff --git a/gio/gtlscertificate.c b/gio/gtlscertificate.c
index ea5f1df..47de03d 100644 (file)
--- a/gio/gtlscertificate.c
+++ b/gio/gtlscertificate.c
@@ -13,9 +13,7 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  */
 
 #include "config.h"
@@ -32,6 +30,7 @@
  * SECTION:gtlscertificate
  * @title: GTlsCertificate
  * @short_description: TLS certificate
+ * @include: gio/gio.h
  * @see_also: #GTlsConnection
  *
  * A certificate used for TLS authentication and encryption.
@@ -139,7 +138,7 @@ g_tls_certificate_class_init (GTlsCertificateClass *class)
    * but cannot be read.
    *
    * PKCS#8 format is supported since 2.32; earlier releases only
-   * support PKCS#1. You can use the <literal>openssl rsa</literal>
+   * support PKCS#1. You can use the `openssl rsa`
    * tool to convert PKCS#8 keys to PKCS#1.
    *
    * Since: 2.28
@@ -156,14 +155,14 @@ g_tls_certificate_class_init (GTlsCertificateClass *class)
    * GTlsCertificate:private-key-pem:
    *
    * The PEM (ASCII) encoded representation of the certificate's
-   * private key in either PKCS#1 format ("<literal>BEGIN RSA PRIVATE
-   * KEY</literal>") or unencrypted PKCS#8 format ("<literal>BEGIN
-   * PRIVATE KEY</literal>"). This property (or the
+   * private key in either PKCS#1 format ("`BEGIN RSA PRIVATE
+   * KEY`") or unencrypted PKCS#8 format ("`BEGIN
+   * PRIVATE KEY`"). This property (or the
    * #GTlsCertificate:private-key property) can be set when
    * constructing a key (eg, from a file), but cannot be read.
    *
    * PKCS#8 format is supported since 2.32; earlier releases only
-   * support PKCS#1. You can use the <literal>openssl rsa</literal>
+   * support PKCS#1. You can use the `openssl rsa`
    * tool to convert PKCS#8 keys to PKCS#1.
    *
    * Since: 2.28
@@ -321,7 +320,7 @@ parse_next_pem_certificate (const gchar **data,
  * If @data includes multiple certificates, only the first one will be
  * parsed.
  *
- * Return value: the new certificate, or %NULL if @data is invalid
+ * Returns: the new certificate, or %NULL if @data is invalid
  *
  * Since: 2.28
  */
@@ -369,7 +368,7 @@ g_tls_certificate_new_from_pem  (const gchar  *data,
  * set @error. Otherwise, this behaves like
  * g_tls_certificate_new_from_pem().
  *
- * Return value: the new certificate, or %NULL on error
+ * Returns: the new certificate, or %NULL on error
  *
  * Since: 2.28
  */
@@ -400,7 +399,7 @@ g_tls_certificate_new_from_file (const gchar  *file,
  * function will return %NULL and set @error. Otherwise, this behaves
  * like g_tls_certificate_new_from_pem().
  *
- * Return value: the new certificate, or %NULL on error
+ * Returns: the new certificate, or %NULL on error
  *
  * Since: 2.28
  */
@@ -447,13 +446,13 @@ g_tls_certificate_new_from_files (const gchar  *cert_file,
  * @file: file containing PEM-encoded certificates to import
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded
+ * Creates one or more #GTlsCertificates from the PEM-encoded
  * data in @file. If @file cannot be read or parsed, the function will
  * return %NULL and set @error. If @file does not contain any
  * PEM-encoded certificates, this will return an empty list and not
  * set @error.
  *
- * Return value: (element-type Gio.TlsCertificate) (transfer full): a
+ * Returns: (element-type Gio.TlsCertificate) (transfer full): a
  * #GList containing #GTlsCertificate objects. You must free the list
  * and its contents when you are done with it.
  *
@@ -477,19 +476,24 @@ g_tls_certificate_list_new_from_file (const gchar  *file,
     {
       gchar *cert_pem;
       GTlsCertificate *cert = NULL;
+      GError *parse_error = NULL;
 
-      cert_pem = parse_next_pem_certificate (&p, end, FALSE, error);
+      cert_pem = parse_next_pem_certificate (&p, end, FALSE, &parse_error);
       if (cert_pem)
-       {
-         cert = g_tls_certificate_new_internal (cert_pem, NULL, error);
-         g_free (cert_pem);
-       }
+        {
+          cert = g_tls_certificate_new_internal (cert_pem, NULL, &parse_error);
+          g_free (cert_pem);
+        }
       if (!cert)
-       {
-         g_list_free_full (queue.head, g_object_unref);
-         queue.head = NULL;
-         break;
-       }
+        {
+          if (parse_error)
+            {
+              g_propagate_error (error, parse_error);
+              g_list_free_full (queue.head, g_object_unref);
+              queue.head = NULL;
+            }
+          break;
+        }
       g_queue_push_tail (&queue, cert);
     }
 
@@ -504,7 +508,7 @@ g_tls_certificate_list_new_from_file (const gchar  *file,
  *
  * Gets the #GTlsCertificate representing @cert's issuer, if known
  *
- * Return value: (transfer none): The certificate of @cert's issuer,
+ * Returns: (transfer none): The certificate of @cert's issuer,
  * or %NULL if @cert is self-signed or signed with an unknown
  * certificate.
  *
@@ -548,7 +552,7 @@ g_tls_certificate_get_issuer (GTlsCertificate  *cert)
  * (All other #GTlsCertificateFlags values will always be set or unset
  * as appropriate.)
  *
- * Return value: the appropriate #GTlsCertificateFlags
+ * Returns: the appropriate #GTlsCertificateFlags
  *
  * Since: 2.28
  */
@@ -571,7 +575,7 @@ g_tls_certificate_verify (GTlsCertificate     *cert,
  * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
  * #GTlsCertificate:private-key-pem properties differ.
  *
- * Return value: whether the same or not
+ * Returns: whether the same or not
  *
  * Since: 2.34
  */