From ab6881ac48d5ac6a7396778edd5fce8b1cfcba0d Mon Sep 17 00:00:00 2001
From: rklec <71322635+rklec@users.noreply.github.com>
Date: Wed, 2 Oct 2024 17:09:53 +0200
Subject: [PATCH 1/3] Update HeaderId to clarify the difference between
 Autosubmitted and Auto-Submitted

This was totally confusing for me why there are two header IDs in MimeKit with the quite very same header. I even suspected a bug or that it is just a legacy API-compatibility thing (one being deprecated, though not stated?).

After some research it turns out, the header is actually defined.
At least for the modern RFC3834 header the keywords are actually also defined by IANA: https://www.iana.org/assignments/auto-submitted-keywords/auto-submitted-keywords.xml (But you don't do mapping to an enum, so introducing this would change the API drastically and be a different/bigger task, so I thought for the code this may not be relevant.)

So to clarify this and ease searching around the web and decrease potential confusion for other developers, IMHO, it is a good idea to just directly point out the basic difference in the (code) doc, directly where you are using it.

For background, I am at https://github.com/jstedfast/MimeKit/issues/938#issuecomment-2388847922 here detecting auto-reply mails for which this header is very important.
---
 MimeKit/HeaderId.cs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/MimeKit/HeaderId.cs b/MimeKit/HeaderId.cs
index 6fc40f74ff..38b282695b 100644
--- a/MimeKit/HeaderId.cs
+++ b/MimeKit/HeaderId.cs
@@ -121,11 +121,18 @@ public enum HeaderId {
 		/// <summary>
 		/// The Auto-Submitted header field.
 		/// </summary>
+		/// <remarks>
+		/// The header as defined in <see href="https://www.rfc-editor.org/rfc/rfc3834">RFC3834</see>
+		/// </remarks>
 		AutoSubmitted,
 
 		/// <summary>
 		/// The Autosubmitted header field.
 		/// </summary>
+		/// <remarks>
+		/// <b>Important:</b> This is more a legacy header as defined in <see href="https://datatracker.ietf.org/doc/html/rfc2156"/>RFC2156</see>. <br>
+		/// Usually, you likely want to use <see cref="AutoSubmitted"/> instead.
+		/// </remarks>
 		Autosubmitted,
 
 		/// <summary>

From dd2302cb649609cb948252529492db020b0a75ac Mon Sep 17 00:00:00 2001
From: rklec <71322635+rklec@users.noreply.github.com>
Date: Wed, 2 Oct 2024 17:10:43 +0200
Subject: [PATCH 2/3] style: add missing dot

---
 MimeKit/HeaderId.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/MimeKit/HeaderId.cs b/MimeKit/HeaderId.cs
index 38b282695b..fbd24161e1 100644
--- a/MimeKit/HeaderId.cs
+++ b/MimeKit/HeaderId.cs
@@ -122,7 +122,7 @@ public enum HeaderId {
 		/// The Auto-Submitted header field.
 		/// </summary>
 		/// <remarks>
-		/// The header as defined in <see href="https://www.rfc-editor.org/rfc/rfc3834">RFC3834</see>
+		/// The header as defined in <see href="https://www.rfc-editor.org/rfc/rfc3834">RFC3834</see>.
 		/// </remarks>
 		AutoSubmitted,
 

From 1722f4522be9e23fc6fa2d8e4f0f31fb9c788f95 Mon Sep 17 00:00:00 2001
From: Jeffrey Stedfast <jestedfa@microsoft.com>
Date: Wed, 2 Oct 2024 11:18:37 -0400
Subject: [PATCH 3/3] Update HeaderId.cs

Improved wording
---
 MimeKit/HeaderId.cs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/MimeKit/HeaderId.cs b/MimeKit/HeaderId.cs
index fbd24161e1..e1908937d4 100644
--- a/MimeKit/HeaderId.cs
+++ b/MimeKit/HeaderId.cs
@@ -130,8 +130,10 @@ public enum HeaderId {
 		/// The Autosubmitted header field.
 		/// </summary>
 		/// <remarks>
-		/// <b>Important:</b> This is more a legacy header as defined in <see href="https://datatracker.ietf.org/doc/html/rfc2156"/>RFC2156</see>. <br>
-		/// Usually, you likely want to use <see cref="AutoSubmitted"/> instead.
+		/// <note type="warning">
+		/// <para>This is a legacy header as defined in <see href="https://datatracker.ietf.org/doc/html/rfc2156"/>RFC2156</see>.</para>
+		/// <para>Most likely, you want to use <see cref="AutoSubmitted"/> instead.</para>
+		/// </note>
 		/// </remarks>
 		Autosubmitted,