diff --git a/configs/config-ccm-psk-tls1_2.h b/configs/config-ccm-psk-tls1_2.h
index aee10b86fe..a783e6b73b 100644
--- a/configs/config-ccm-psk-tls1_2.h
+++ b/configs/config-ccm-psk-tls1_2.h
@@ -1,6 +1,9 @@
-/*
- *  Minimal configuration for TLS 1.2 with PSK and AES-CCM ciphersuites
+/**
+ * \file config-ccm-psk-tls1_2.h
  *
+ * \brief Minimal configuration for TLS 1.2 with PSK and AES-CCM ciphersuites
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/configs/config-mini-tls1_1.h b/configs/config-mini-tls1_1.h
index e22363d1a3..013bc0300d 100644
--- a/configs/config-mini-tls1_1.h
+++ b/configs/config-mini-tls1_1.h
@@ -1,6 +1,9 @@
-/*
- *  Minimal configuration for TLS 1.1 (RFC 4346)
+/**
+ * \file config-mini-tls1_1.h
  *
+ * \brief Minimal configuration for TLS 1.1 (RFC 4346)
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/configs/config-no-entropy.h b/configs/config-no-entropy.h
index 73758602ab..b4a0930b9c 100644
--- a/configs/config-no-entropy.h
+++ b/configs/config-no-entropy.h
@@ -1,6 +1,9 @@
 /**
- *  Minimal configuration of features that do not require an entropy source
+ * \file config-no-entropy.h
  *
+ * \brief Minimal configuration of features that do not require an entropy source
+ */
+/*
  *  Copyright (C) 2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/configs/config-picocoin.h b/configs/config-picocoin.h
index 26b24a9e2a..5d41f282f1 100644
--- a/configs/config-picocoin.h
+++ b/configs/config-picocoin.h
@@ -1,6 +1,9 @@
-/*
- *  Reduced configuration used by Picocoin.
+/**
+ * \file config-picocoin.h
  *
+ * \brief Reduced configuration used by Picocoin.
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/configs/config-suite-b.h b/configs/config-suite-b.h
index 3c4804c79d..18e2c40369 100644
--- a/configs/config-suite-b.h
+++ b/configs/config-suite-b.h
@@ -1,6 +1,9 @@
-/*
- *  Minimal configuration for TLS NSA Suite B Profile (RFC 6460)
+/**
+ * \file config-suite-b.h
  *
+ * \brief Minimal configuration for TLS NSA Suite B Profile (RFC 6460)
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/configs/config-thread.h b/configs/config-thread.h
index 990fe08c6c..25db16bf0f 100644
--- a/configs/config-thread.h
+++ b/configs/config-thread.h
@@ -1,6 +1,9 @@
-/*
- *  Minimal configuration for using TLS as part of Thread
+/**
+ * \file config-thread.h
  *
+ * \brief Minimal configuration for using TLS as part of Thread
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index c8dd0f355b..71dcea9e55 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -2,7 +2,8 @@
  * \file aes.h
  *
  * \brief AES block cipher
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/aesni.h b/include/mbedtls/aesni.h
index b1b7f1cdec..746baa0e17 100644
--- a/include/mbedtls/aesni.h
+++ b/include/mbedtls/aesni.h
@@ -2,7 +2,8 @@
  * \file aesni.h
  *
  * \brief AES-NI for hardware AES acceleration on some Intel processors
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/arc4.h b/include/mbedtls/arc4.h
index 5fc5395a8c..26de33f8d5 100644
--- a/include/mbedtls/arc4.h
+++ b/include/mbedtls/arc4.h
@@ -2,7 +2,8 @@
  * \file arc4.h
  *
  * \brief The ARCFOUR stream cipher
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/asn1.h b/include/mbedtls/asn1.h
index e159e57ea0..fde328a128 100644
--- a/include/mbedtls/asn1.h
+++ b/include/mbedtls/asn1.h
@@ -2,7 +2,8 @@
  * \file asn1.h
  *
  * \brief Generic ASN.1 parsing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/asn1write.h b/include/mbedtls/asn1write.h
index 73ff32b669..f76fc807d0 100644
--- a/include/mbedtls/asn1write.h
+++ b/include/mbedtls/asn1write.h
@@ -2,7 +2,8 @@
  * \file asn1write.h
  *
  * \brief ASN.1 buffer writing functionality
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/base64.h b/include/mbedtls/base64.h
index 352c652db9..7a64f52163 100644
--- a/include/mbedtls/base64.h
+++ b/include/mbedtls/base64.h
@@ -2,7 +2,8 @@
  * \file base64.h
  *
  * \brief RFC 1521 base64 encoding/decoding
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h
index 0b40015424..c20b367803 100644
--- a/include/mbedtls/bignum.h
+++ b/include/mbedtls/bignum.h
@@ -1,8 +1,9 @@
 /**
  * \file bignum.h
  *
- * \brief  Multi-precision integer library
- *
+ * \brief Multi-precision integer library
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/blowfish.h b/include/mbedtls/blowfish.h
index 34626eef48..6593730e4d 100644
--- a/include/mbedtls/blowfish.h
+++ b/include/mbedtls/blowfish.h
@@ -2,7 +2,8 @@
  * \file blowfish.h
  *
  * \brief Blowfish block cipher
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/bn_mul.h b/include/mbedtls/bn_mul.h
index cac3f14577..354c1cc1ab 100644
--- a/include/mbedtls/bn_mul.h
+++ b/include/mbedtls/bn_mul.h
@@ -1,8 +1,9 @@
 /**
  * \file bn_mul.h
  *
- * \brief  Multi-precision integer library
- *
+ * \brief Multi-precision integer library
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/camellia.h b/include/mbedtls/camellia.h
index 0424d623fb..107056fc66 100644
--- a/include/mbedtls/camellia.h
+++ b/include/mbedtls/camellia.h
@@ -2,7 +2,8 @@
  * \file camellia.h
  *
  * \brief Camellia block cipher
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ccm.h b/include/mbedtls/ccm.h
index 579402fd48..acd94adb88 100644
--- a/include/mbedtls/ccm.h
+++ b/include/mbedtls/ccm.h
@@ -2,7 +2,8 @@
  * \file ccm.h
  *
  * \brief Counter with CBC-MAC (CCM) for 128-bit block ciphers
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/certs.h b/include/mbedtls/certs.h
index ca49086e4f..8dab7b5ce8 100644
--- a/include/mbedtls/certs.h
+++ b/include/mbedtls/certs.h
@@ -2,7 +2,8 @@
  * \file certs.h
  *
  * \brief Sample certificates and DHM parameters for testing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h
index fa72454e53..1143aa2687 100644
--- a/include/mbedtls/check_config.h
+++ b/include/mbedtls/check_config.h
@@ -2,7 +2,8 @@
  * \file check_config.h
  *
  * \brief Consistency checks for configuration options
- *
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index b12e38843a..b92a8dbb9f 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -4,7 +4,8 @@
  * \brief Generic cipher wrapper.
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/cipher_internal.h b/include/mbedtls/cipher_internal.h
index 6c58bcc525..969ff9ccb8 100644
--- a/include/mbedtls/cipher_internal.h
+++ b/include/mbedtls/cipher_internal.h
@@ -4,7 +4,8 @@
  * \brief Cipher wrappers.
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index 4d3f2d2f4f..a7f7f45e9c 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -3,7 +3,8 @@
  *
  * \brief Cipher-based Message Authentication Code (CMAC) Mode for
  *        Authentication
- *
+ */
+/*
  *  Copyright (C) 2015-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/compat-1.3.h b/include/mbedtls/compat-1.3.h
index bba1d2c247..600a0f154c 100644
--- a/include/mbedtls/compat-1.3.h
+++ b/include/mbedtls/compat-1.3.h
@@ -5,7 +5,8 @@
  *  for the PolarSSL naming conventions.
  *
  * \deprecated Use the new names directly instead
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 70039897d2..5e6b63e82b 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -6,7 +6,8 @@
  *  This set of compile-time options may be used to enable
  *  or disable features selectively, and reduce the global
  *  memory footprint.
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 059d3c5c9a..01cd826a17 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -2,7 +2,8 @@
  * \file ctr_drbg.h
  *
  * \brief CTR_DRBG based on AES-256 (NIST SP 800-90)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/debug.h b/include/mbedtls/debug.h
index 2957996407..ef8db67ff1 100644
--- a/include/mbedtls/debug.h
+++ b/include/mbedtls/debug.h
@@ -2,7 +2,8 @@
  * \file debug.h
  *
  * \brief Functions for controlling and providing debug output from the library.
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/des.h b/include/mbedtls/des.h
index 5ca2ecf2e0..7f8f27eea3 100644
--- a/include/mbedtls/des.h
+++ b/include/mbedtls/des.h
@@ -2,7 +2,8 @@
  * \file des.h
  *
  * \brief DES block cipher
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index f9725ab095..d017b380ea 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -2,7 +2,8 @@
  * \file dhm.h
  *
  * \brief Diffie-Hellman-Merkle key exchange
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index 625a281923..14a362b197 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -2,7 +2,8 @@
  * \file ecdh.h
  *
  * \brief Elliptic curve Diffie-Hellman
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index a277715b3d..6c6ae294f9 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -2,7 +2,8 @@
  * \file ecdsa.h
  *
  * \brief Elliptic curve DSA
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index 161a5b213f..6fcffc777a 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -2,7 +2,8 @@
  * \file ecjpake.h
  *
  * \brief Elliptic curve J-PAKE
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index dad9aef002..977134059f 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -2,7 +2,8 @@
  * \file ecp.h
  *
  * \brief Elliptic curves over GF(p)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ecp_internal.h b/include/mbedtls/ecp_internal.h
index 2991e26dd9..8a6d517ed0 100644
--- a/include/mbedtls/ecp_internal.h
+++ b/include/mbedtls/ecp_internal.h
@@ -3,7 +3,8 @@
  *
  * \brief Function declarations for alternative implementation of elliptic curve
  * point arithmetic.
- *
+ */
+/*
  *  Copyright (C) 2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/entropy.h b/include/mbedtls/entropy.h
index 747aca4dfa..3161777462 100644
--- a/include/mbedtls/entropy.h
+++ b/include/mbedtls/entropy.h
@@ -2,7 +2,8 @@
  * \file entropy.h
  *
  * \brief Entropy accumulator implementation
- *
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/entropy_poll.h b/include/mbedtls/entropy_poll.h
index 81258d5f39..94dd657eb9 100644
--- a/include/mbedtls/entropy_poll.h
+++ b/include/mbedtls/entropy_poll.h
@@ -2,7 +2,8 @@
  * \file entropy_poll.h
  *
  * \brief Platform-specific and custom entropy polling functions
- *
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h
index 4eb7b78ebf..bd4ca90f04 100644
--- a/include/mbedtls/error.h
+++ b/include/mbedtls/error.h
@@ -2,7 +2,8 @@
  * \file error.h
  *
  * \brief Error to string translation
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 8f3b565757..f1019861dc 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -2,7 +2,8 @@
  * \file gcm.h
  *
  * \brief Galois/Counter mode for 128-bit block ciphers
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/havege.h b/include/mbedtls/havege.h
index dac5d31138..d4cb3ed38d 100644
--- a/include/mbedtls/havege.h
+++ b/include/mbedtls/havege.h
@@ -2,7 +2,8 @@
  * \file havege.h
  *
  * \brief HAVEGE: HArdware Volatile Entropy Gathering and Expansion
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/hmac_drbg.h b/include/mbedtls/hmac_drbg.h
index e010558028..e0821cf788 100644
--- a/include/mbedtls/hmac_drbg.h
+++ b/include/mbedtls/hmac_drbg.h
@@ -2,7 +2,8 @@
  * \file hmac_drbg.h
  *
  * \brief HMAC_DRBG (NIST SP 800-90A)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h
index 89be847cee..f23bad40aa 100644
--- a/include/mbedtls/md.h
+++ b/include/mbedtls/md.h
@@ -4,7 +4,8 @@
  * \brief Generic message digest wrapper
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/md2.h b/include/mbedtls/md2.h
index 0f93fbf427..89fcf36ec6 100644
--- a/include/mbedtls/md2.h
+++ b/include/mbedtls/md2.h
@@ -2,7 +2,8 @@
  * \file md2.h
  *
  * \brief MD2 message digest algorithm (hash function)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/md4.h b/include/mbedtls/md4.h
index 45214d41d9..f086abbdb0 100644
--- a/include/mbedtls/md4.h
+++ b/include/mbedtls/md4.h
@@ -2,7 +2,8 @@
  * \file md4.h
  *
  * \brief MD4 message digest algorithm (hash function)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/md5.h b/include/mbedtls/md5.h
index 5a64061aa0..378f63f587 100644
--- a/include/mbedtls/md5.h
+++ b/include/mbedtls/md5.h
@@ -2,7 +2,8 @@
  * \file md5.h
  *
  * \brief MD5 message digest algorithm (hash function)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/md_internal.h b/include/mbedtls/md_internal.h
index e2441bbc49..d051730646 100644
--- a/include/mbedtls/md_internal.h
+++ b/include/mbedtls/md_internal.h
@@ -6,7 +6,8 @@
  * \warning This in an internal header. Do not include directly.
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/memory_buffer_alloc.h b/include/mbedtls/memory_buffer_alloc.h
index d5df316fdd..705f9a6369 100644
--- a/include/mbedtls/memory_buffer_alloc.h
+++ b/include/mbedtls/memory_buffer_alloc.h
@@ -2,7 +2,8 @@
  * \file memory_buffer_alloc.h
  *
  * \brief Buffer-based memory allocator
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/net.h b/include/mbedtls/net.h
index 774559b3cf..28ae8217c0 100644
--- a/include/mbedtls/net.h
+++ b/include/mbedtls/net.h
@@ -3,6 +3,9 @@
  *
  * \brief Deprecated header file that includes mbedtls/net_sockets.h
  *
+ * \deprecated Superseded by mbedtls/net_sockets.h
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
@@ -19,8 +22,6 @@
  *  limitations under the License.
  *
  *  This file is part of mbed TLS (https://tls.mbed.org)
- *
- * \deprecated Superseded by mbedtls/net_sockets.h
  */
 
 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
diff --git a/include/mbedtls/net_sockets.h b/include/mbedtls/net_sockets.h
index de335526fe..54e612cc5e 100644
--- a/include/mbedtls/net_sockets.h
+++ b/include/mbedtls/net_sockets.h
@@ -2,7 +2,8 @@
  * \file net_sockets.h
  *
  * \brief Network communication functions
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/oid.h b/include/mbedtls/oid.h
index fcecdafdca..bf2ef5ece4 100644
--- a/include/mbedtls/oid.h
+++ b/include/mbedtls/oid.h
@@ -2,7 +2,8 @@
  * \file oid.h
  *
  * \brief Object Identifier (OID) database
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/padlock.h b/include/mbedtls/padlock.h
index 2045a5ab64..677936ebf8 100644
--- a/include/mbedtls/padlock.h
+++ b/include/mbedtls/padlock.h
@@ -3,7 +3,8 @@
  *
  * \brief VIA PadLock ACE for HW encryption/decryption supported by some
  *        processors
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pem.h b/include/mbedtls/pem.h
index 54dc02d7cd..2cf4c0a709 100644
--- a/include/mbedtls/pem.h
+++ b/include/mbedtls/pem.h
@@ -2,7 +2,8 @@
  * \file pem.h
  *
  * \brief Privacy Enhanced Mail (PEM) decoding
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index f9f9b9bb09..28f6150077 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -2,7 +2,8 @@
  * \file pk.h
  *
  * \brief Public Key abstraction layer
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pk_internal.h b/include/mbedtls/pk_internal.h
index 01d0f214bc..3dae0fc5b2 100644
--- a/include/mbedtls/pk_internal.h
+++ b/include/mbedtls/pk_internal.h
@@ -1,8 +1,9 @@
 /**
- * \file pk.h
+ * \file pk_internal.h
  *
  * \brief Public Key abstraction layer: wrapper functions
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pkcs11.h b/include/mbedtls/pkcs11.h
index 2e88928137..bf65c55a79 100644
--- a/include/mbedtls/pkcs11.h
+++ b/include/mbedtls/pkcs11.h
@@ -4,7 +4,8 @@
  * \brief Wrapper for PKCS#11 library libpkcs11-helper
  *
  * \author Adriaan de Jong <dejong@fox-it.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pkcs12.h b/include/mbedtls/pkcs12.h
index 9b2d904591..a621ef5b15 100644
--- a/include/mbedtls/pkcs12.h
+++ b/include/mbedtls/pkcs12.h
@@ -2,7 +2,8 @@
  * \file pkcs12.h
  *
  * \brief PKCS#12 Personal Information Exchange Syntax
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/pkcs5.h b/include/mbedtls/pkcs5.h
index ec5cb9e744..9a3c9fddcc 100644
--- a/include/mbedtls/pkcs5.h
+++ b/include/mbedtls/pkcs5.h
@@ -4,7 +4,8 @@
  * \brief PKCS#5 functions
  *
  * \author Mathias Olsson <mathias@kompetensum.com>
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/platform.h b/include/mbedtls/platform.h
index 35010f8852..e051751189 100644
--- a/include/mbedtls/platform.h
+++ b/include/mbedtls/platform.h
@@ -2,7 +2,8 @@
  * \file platform.h
  *
  * \brief mbed TLS Platform abstraction layer
- *
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/platform_time.h b/include/mbedtls/platform_time.h
index abb3431420..2ed36f56c9 100644
--- a/include/mbedtls/platform_time.h
+++ b/include/mbedtls/platform_time.h
@@ -2,7 +2,8 @@
  * \file platform_time.h
  *
  * \brief mbed TLS Platform time abstraction
- *
+ */
+/*
  *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ripemd160.h b/include/mbedtls/ripemd160.h
index 7083fc8599..ae365f3d62 100644
--- a/include/mbedtls/ripemd160.h
+++ b/include/mbedtls/ripemd160.h
@@ -2,7 +2,8 @@
  * \file ripemd160.h
  *
  * \brief RIPE MD-160 message digest
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index d7503ac831..a4a4716830 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -2,7 +2,8 @@
  * \file rsa.h
  *
  * \brief The RSA public-key cryptosystem
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/rsa_internal.h b/include/mbedtls/rsa_internal.h
index 7e6a2ecd97..bcb3c9401d 100644
--- a/include/mbedtls/rsa_internal.h
+++ b/include/mbedtls/rsa_internal.h
@@ -2,7 +2,8 @@
  * \file rsa_internal.h
  *
  * \brief Context-independent RSA helper functions
- *
+ */
+/*
  *  Copyright (C) 2006-2017, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index 7a67c6c1fb..d98f166f96 100644
--- a/include/mbedtls/sha1.h
+++ b/include/mbedtls/sha1.h
@@ -2,7 +2,8 @@
  * \file sha1.h
  *
  * \brief SHA-1 cryptographic hash function
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index f8041adf08..1c872dd55f 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -2,7 +2,8 @@
  * \file sha256.h
  *
  * \brief SHA-224 and SHA-256 cryptographic hash function
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 627694f425..542dc990bf 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -2,7 +2,8 @@
  * \file sha512.h
  *
  * \brief SHA-384 and SHA-512 cryptographic hash function
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index e98101e19d..7ad71cc315 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2,7 +2,8 @@
  * \file ssl.h
  *
  * \brief SSL/TLS functions.
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ssl_cache.h b/include/mbedtls/ssl_cache.h
index 3734bb7274..ec081e6d24 100644
--- a/include/mbedtls/ssl_cache.h
+++ b/include/mbedtls/ssl_cache.h
@@ -2,7 +2,8 @@
  * \file ssl_cache.h
  *
  * \brief SSL session cache implementation
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ssl_ciphersuites.h b/include/mbedtls/ssl_ciphersuites.h
index 9101d9cc7c..545468a510 100644
--- a/include/mbedtls/ssl_ciphersuites.h
+++ b/include/mbedtls/ssl_ciphersuites.h
@@ -2,7 +2,8 @@
  * \file ssl_ciphersuites.h
  *
  * \brief SSL Ciphersuites for mbed TLS
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ssl_cookie.h b/include/mbedtls/ssl_cookie.h
index 037e1c3112..80b65bbbb9 100644
--- a/include/mbedtls/ssl_cookie.h
+++ b/include/mbedtls/ssl_cookie.h
@@ -2,7 +2,8 @@
  * \file ssl_cookie.h
  *
  * \brief DTLS cookie callbacks implementation
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ssl_internal.h b/include/mbedtls/ssl_internal.h
index 756360b181..509927ad94 100644
--- a/include/mbedtls/ssl_internal.h
+++ b/include/mbedtls/ssl_internal.h
@@ -1,8 +1,9 @@
 /**
- * \file ssl_ticket.h
+ * \file ssl_internal.h
  *
  * \brief Internal functions shared by the SSL modules
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/ssl_ticket.h b/include/mbedtls/ssl_ticket.h
index 7c6bc61bfb..93ad46ac9c 100644
--- a/include/mbedtls/ssl_ticket.h
+++ b/include/mbedtls/ssl_ticket.h
@@ -2,7 +2,8 @@
  * \file ssl_ticket.h
  *
  * \brief TLS server ticket callbacks implementation
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/threading.h b/include/mbedtls/threading.h
index b0c34ecc74..58e6db2f3a 100644
--- a/include/mbedtls/threading.h
+++ b/include/mbedtls/threading.h
@@ -2,7 +2,8 @@
  * \file threading.h
  *
  * \brief Threading abstraction layer
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/timing.h b/include/mbedtls/timing.h
index bfb8579a07..2c497bf4eb 100644
--- a/include/mbedtls/timing.h
+++ b/include/mbedtls/timing.h
@@ -2,7 +2,8 @@
  * \file timing.h
  *
  * \brief Portable interface to timeouts and to the CPU cycle counter
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/version.h b/include/mbedtls/version.h
index 3b209a6b07..8af6f01708 100644
--- a/include/mbedtls/version.h
+++ b/include/mbedtls/version.h
@@ -2,7 +2,8 @@
  * \file version.h
  *
  * \brief Run-time version information
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/x509.h b/include/mbedtls/x509.h
index d7e318dfdc..d6db9c6e37 100644
--- a/include/mbedtls/x509.h
+++ b/include/mbedtls/x509.h
@@ -2,7 +2,8 @@
  * \file x509.h
  *
  * \brief X.509 generic defines and structures
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/x509_crl.h b/include/mbedtls/x509_crl.h
index 7988439900..08a4283a67 100644
--- a/include/mbedtls/x509_crl.h
+++ b/include/mbedtls/x509_crl.h
@@ -2,7 +2,8 @@
  * \file x509_crl.h
  *
  * \brief X.509 certificate revocation list parsing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index b7a509831f..2dbb7ec964 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -2,7 +2,8 @@
  * \file x509_crt.h
  *
  * \brief X.509 certificate parsing and writing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/x509_csr.h b/include/mbedtls/x509_csr.h
index fe9843cb54..0c6ccad78d 100644
--- a/include/mbedtls/x509_csr.h
+++ b/include/mbedtls/x509_csr.h
@@ -2,7 +2,8 @@
  * \file x509_csr.h
  *
  * \brief X.509 certificate signing request parsing and writing
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
diff --git a/include/mbedtls/xtea.h b/include/mbedtls/xtea.h
index b073f84efa..1d01e56f83 100644
--- a/include/mbedtls/xtea.h
+++ b/include/mbedtls/xtea.h
@@ -2,7 +2,8 @@
  * \file xtea.h
  *
  * \brief XTEA block cipher (32-bit)
- *
+ */
+/*
  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *