From 9f163b0cee78e5de1cd4439617f51b32f24232dd Mon Sep 17 00:00:00 2001
From: Aayush Goel <81844215+Aayush-Goel-04@users.noreply.github.com>
Date: Fri, 25 Aug 2023 22:01:29 +0530
Subject: [PATCH 1/5] Update format.md

Documentation for COM feature addition in https://github.com/mandiant/capa/pull/1738
---
 doc/format.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/doc/format.md b/doc/format.md
index c72ae9e54..27d2722ac 100644
--- a/doc/format.md
+++ b/doc/format.md
@@ -343,6 +343,7 @@ The following features are relevant at this scope and above:
   - [number](#number)
   - [string and substring](#string-and-substring)
   - [bytes](#bytes)
+  - [com](#com)
   - [offset](#offset)
   - [mnemonic](#mnemonic)
   - [operand](#operand)
@@ -501,6 +502,33 @@ Example rule elements:
     bytes: 01 14 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = CLSID_ShellLink
     bytes: EE 14 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = IID_IShellLink
 
+### com
+COM features represent Component Object Model (COM) interfaces and classes used in the program's logic. They help identify interactions with COM objects, methods, properties, and interfaces. The parameter is the name of the COM.
+
+Example:
+
+```yaml
+- com/class: InternetExplorer #bytes: 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = CLSID_InternetExplorer
+- com/interface: IWebBrowser2 #bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IID_IWebBrowser2
+```
+
+Rule parsers will translate the above rule to its bytes and string representation using the COM name by fetching the GUIDs from the COM database.
+
+Translated Representation:
+
+```yaml
+- or:
+  - bytes : 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = InternetExplorer as bytes
+  - string : "0002DF01-0000-0000-C000-000000000046"
+    description: InternetExplorer as guid string
+- or:
+  - bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IWebBrowser2 as bytes
+  - string: "D30C1661-CDAF-11D0-8A3E-00C04FC9E26E"
+    description: IWebBrowser2 as guid string
+```
+
+Note: I added the description field for the bytes entries in the translated representation to match the provided example where the comments are included. This helps to maintain consistency in the documentation.
+
 ### offset
 A structure offset referenced by the logic of the program.
 This should not be a stack offset.

From cdfb01762b8ba7acd2b954d355212e95ae0622e2 Mon Sep 17 00:00:00 2001
From: Aayush Goel <81844215+Aayush-Goel-04@users.noreply.github.com>
Date: Fri, 25 Aug 2023 22:07:36 +0530
Subject: [PATCH 2/5] Update format.md

---
 doc/format.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/format.md b/doc/format.md
index 27d2722ac..a00fc2528 100644
--- a/doc/format.md
+++ b/doc/format.md
@@ -512,19 +512,19 @@ Example:
 - com/interface: IWebBrowser2 #bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IID_IWebBrowser2
 ```
 
-Rule parsers will translate the above rule to its bytes and string representation using the COM name by fetching the GUIDs from the COM database.
+Rule parsers will translate the above rule to its `bytes` and `string` representation by fetching the GUIDs from the COM database using the COM name.
 
 Translated Representation:
 
 ```yaml
 - or:
-  - bytes : 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = InternetExplorer as bytes
   - string : "0002DF01-0000-0000-C000-000000000046"
     description: InternetExplorer as guid string
+  - bytes : 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = InternetExplorer as bytes
 - or:
-  - bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IWebBrowser2 as bytes
   - string: "D30C1661-CDAF-11D0-8A3E-00C04FC9E26E"
     description: IWebBrowser2 as guid string
+  - bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IWebBrowser2 as bytes
 ```
 
 Note: I added the description field for the bytes entries in the translated representation to match the provided example where the comments are included. This helps to maintain consistency in the documentation.

From 1a8a45b99f670f5ca6c0aa0cbc0a7068c4a2a1f9 Mon Sep 17 00:00:00 2001
From: Aayush Goel <81844215+Aayush-Goel-04@users.noreply.github.com>
Date: Mon, 28 Aug 2023 16:23:41 +0530
Subject: [PATCH 3/5] Apply suggestions from code review

Co-authored-by: Moritz <mr-tz@users.noreply.github.com>
---
 doc/format.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/format.md b/doc/format.md
index a00fc2528..45299ee7b 100644
--- a/doc/format.md
+++ b/doc/format.md
@@ -503,23 +503,23 @@ Example rule elements:
     bytes: EE 14 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = IID_IShellLink
 
 ### com
-COM features represent Component Object Model (COM) interfaces and classes used in the program's logic. They help identify interactions with COM objects, methods, properties, and interfaces. The parameter is the name of the COM.
+COM features represent Component Object Model (COM) interfaces and classes used in the program's logic. They help identify interactions with COM objects, methods, properties, and interfaces. The parameter is the name of the COM class or interface. This feature allows you to list human-readable names instead of the byte representations found in the program.
 
-Example:
+Examples:
 
 ```yaml
-- com/class: InternetExplorer #bytes: 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = CLSID_InternetExplorer
-- com/interface: IWebBrowser2 #bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IID_IWebBrowser2
+- com/class: InternetExplorer  # bytes: 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = CLSID_InternetExplorer
+- com/interface: IWebBrowser2  # bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IID_IWebBrowser2
 ```
 
-Rule parsers will translate the above rule to its `bytes` and `string` representation by fetching the GUIDs from the COM database using the COM name.
+The rule parser translates com features to their `bytes` and `string` representation by fetching the GUIDs from an internal COM database.
 
-Translated Representation:
+Translated representation of the above rule:
 
 ```yaml
 - or:
   - string : "0002DF01-0000-0000-C000-000000000046"
-    description: InternetExplorer as guid string
+    description: InternetExplorer as GUID string
   - bytes : 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = InternetExplorer as bytes
 - or:
   - string: "D30C1661-CDAF-11D0-8A3E-00C04FC9E26E"
@@ -527,7 +527,7 @@ Translated Representation:
   - bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IWebBrowser2 as bytes
 ```
 
-Note: I added the description field for the bytes entries in the translated representation to match the provided example where the comments are included. This helps to maintain consistency in the documentation.
+Note: The automatically added descriptions help to maintain consistency and improve documentation.
 
 ### offset
 A structure offset referenced by the logic of the program.

From 2b5eb58a4724e683f9737451b6985787e9989695 Mon Sep 17 00:00:00 2001
From: Aayush Goel <81844215+Aayush-Goel-04@users.noreply.github.com>
Date: Mon, 28 Aug 2023 16:24:38 +0530
Subject: [PATCH 4/5] Update format.md

---
 doc/format.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/format.md b/doc/format.md
index 45299ee7b..c202c677c 100644
--- a/doc/format.md
+++ b/doc/format.md
@@ -523,7 +523,7 @@ Translated representation of the above rule:
   - bytes : 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = InternetExplorer as bytes
 - or:
   - string: "D30C1661-CDAF-11D0-8A3E-00C04FC9E26E"
-    description: IWebBrowser2 as guid string
+    description: IWebBrowser2 as GUID string
   - bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IWebBrowser2 as bytes
 ```
 
@@ -876,4 +876,4 @@ features:
         - number: 0x3320646E = "3 dn"
         - number: 0x79622D32 = "yb-2"
         - number: 0x6B206574 = "k et"
-```      
\ No newline at end of file
+```      

From b47c3a7be6abd039ed82ef59fbc3871d1b7cd856 Mon Sep 17 00:00:00 2001
From: Aayush Goel <81844215+Aayush-Goel-04@users.noreply.github.com>
Date: Wed, 30 Aug 2023 01:02:00 +0530
Subject: [PATCH 5/5] Update format.md

---
 doc/format.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/format.md b/doc/format.md
index c202c677c..be661de44 100644
--- a/doc/format.md
+++ b/doc/format.md
@@ -519,12 +519,12 @@ Translated representation of the above rule:
 ```yaml
 - or:
   - string : "0002DF01-0000-0000-C000-000000000046"
-    description: InternetExplorer as GUID string
-  - bytes : 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = InternetExplorer as bytes
+    description: CLSID_InternetExplorer as GUID string
+  - bytes : 01 DF 02 00 00 00 00 00 C0 00 00 00 00 00 00 46 = CLSID_InternetExplorer as bytes
 - or:
   - string: "D30C1661-CDAF-11D0-8A3E-00C04FC9E26E"
-    description: IWebBrowser2 as GUID string
-  - bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IWebBrowser2 as bytes
+    description: IID_IWebBrowser2 as GUID string
+  - bytes: 61 16 0C D3 AF CD D0 11 8A 3E 00 C0 4F C9 E2 6E = IID_IWebBrowser2 as bytes
 ```
 
 Note: The automatically added descriptions help to maintain consistency and improve documentation.