diff --git a/src/grpc/doc/src/qtgrpc-shared.qdocinc b/src/grpc/doc/src/qtgrpc-shared.qdocinc
index cede8ec2..d8bd4506 100644
--- a/src/grpc/doc/src/qtgrpc-shared.qdocinc
+++ b/src/grpc/doc/src/qtgrpc-shared.qdocinc
@@ -26,3 +26,12 @@
     \l{QGrpcOperation::} {finished} signal is emitted. After receiving this
     signal, the handler can be safely reassigned or destroyed.
 //! [rpc-lifetime-note]
+
+//! [http2-metadata-note]
+    \note QGrpcHttp2Channel transports metadata as HTTP/2 headers. \b{Keys} are
+    case-insensitive ASCII strings. You must avoid using the internal prefixes:
+    \c{:} (pseudo-header), \c{grpc-}, or \c{qtgrpc-}. \b{Values} may be either
+    ASCII strings or binary data. For more information, see
+    \l{https://www.rfc-editor.org/rfc/rfc7540.html#section-8.1.2}{RFC 7540,
+    Section 8.1.2}.
+//! [http2-metadata-note]
diff --git a/src/grpc/qgrpccommonoptions.cpp b/src/grpc/qgrpccommonoptions.cpp
index 74b40620..3713a163 100644
--- a/src/grpc/qgrpccommonoptions.cpp
+++ b/src/grpc/qgrpccommonoptions.cpp
@@ -23,6 +23,8 @@ QtGrpcPrivate::toHash(const QMultiHash<QByteArray, QByteArray> &multiHash)
 //! [metadata]
     Returns the metadata. If this field is unset, returns empty
     metadata.
+
+    \include qtgrpc-shared.qdocinc http2-metadata-note
 //! [metadata]
 */
 const QHash<QByteArray, QByteArray> &QGrpcCommonOptions::metadata() const & noexcept
@@ -46,8 +48,7 @@ QHash<QByteArray, QByteArray> QGrpcCommonOptions::metadata() &&
 //! [set-metadata]
     Sets the \a metadata and returns a reference to the updated object.
 
-    When using QGrpcHttp2Channel, the metadata is converted to HTTP/2 headers
-    and added to the gRPC request.
+    \include qtgrpc-shared.qdocinc http2-metadata-note
 //! [set-metadata]
 */
 void QGrpcCommonOptions::setMetadata(const QHash<QByteArray, QByteArray> &md)
@@ -142,6 +143,8 @@ void QGrpcCommonOptions::setMetadata(QMultiHash<QByteArray, QByteArray> &&md)
     Adds \a key and \a value to the \l metadata if the exact pair is not already contained.
     The same key may appear multiple times with different values.
 
+    \include qtgrpc-shared.qdocinc http2-metadata-note
+
     \sa {metadata(QtGrpc::MultiValue_t)}{metadata()} {setMetadata(const
     QMultiHash<QByteArray, QByteArray>&)}{setMetadata()}
 //! [add-metadata]
diff --git a/src/grpc/qgrpcoperation.cpp b/src/grpc/qgrpcoperation.cpp
index 47b8458c..7f699b9e 100644
--- a/src/grpc/qgrpcoperation.cpp
+++ b/src/grpc/qgrpcoperation.cpp
@@ -183,13 +183,12 @@ const QHash<QByteArray, QByteArray> &QGrpcOperation::metadata() const & noexcept
     established. It may include key-value pairs that provide context for the
     call.
 
-    \note For \l {QGrpcHttp2Channel} {HTTP/2 channels}, this is delivered
-    via response headers.
+    \include qtgrpc-shared.qdocinc http2-metadata-note
 //! [serverInitialMetadata]
 
     The metadata may contain multiple entries under the same key.
 
-    \sa serverTrailingMetadata()
+    \sa serverInitialMetadataReceived() serverTrailingMetadata()
 */
 const QMultiHash<QByteArray, QByteArray> &QGrpcOperation::serverInitialMetadata() const & noexcept
 {
@@ -208,11 +207,12 @@ const QMultiHash<QByteArray, QByteArray> &QGrpcOperation::serverInitialMetadata(
     have been sent and just before the RPC completes. It may include key-value
     pairs providing additional context about the completed call.
 
-    \note For \l {QGrpcHttp2Channel} {HTTP/2 channels}, this is delivered
-    via response trailers.
+    \include qtgrpc-shared.qdocinc http2-metadata-note
 //! [serverTrailingMetadata]
 
     The metadata may contain multiple entries under the same key.
+
+    \sa serverInitialMetadata()
 */
 const QMultiHash<QByteArray, QByteArray> &QGrpcOperation::serverTrailingMetadata() const & noexcept
 {