From 49bb3025761c0556333b674905f5f1fec40073c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mario=20Dom=C3=ADnguez=20L=C3=B3pez?=
 <116071334+Mario-DL@users.noreply.github.com>
Date: Fri, 10 May 2024 10:43:08 +0200
Subject: [PATCH] Extend ``@key`` annotation documentation (#340)

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>
---
 articles/115_idl.md | 44 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/articles/115_idl.md b/articles/115_idl.md
index b93d73a85..b4ebe42f2 100644
--- a/articles/115_idl.md
+++ b/articles/115_idl.md
@@ -264,7 +264,49 @@ If a cell is blank then the default mapping is used.
 
 #### 8.3.2.1 @key Annotation
 
-While the key annotation doesn't affect the generated ROS data types directly it is being passed through to the (DDS) vendor specific code generators.
+[ROS 2 nodes](ros_on_dds.html) exchange information of a certain real world object by means of topics.
+Every message in a topic is known as *data sample* and represents an update to the status of the object.
+
+Topic instances are a way of multiplexing the transmission of updates of several objects of the same logical kind over the same resource, i.e. the topic.
+In a *keyed topic*, every message is associated with a topic instance and each topic instance is identified by a unique key.
+In this sense, keys can be thought as the *primary key* of a database.
+This key allows nodes to update different states of the same kind.
+In consequence, all data samples sharing the same key value refer to the same object.
+
+The `@key` annotation allows indicating that a data member is part of the key, which can have zero or more key fields and can be applied to structure fields of various types.
+The following example shows how to define a keyed message using the IDL format:
+
+```
+# KeyedMsgName.idl
+module package_name {
+  module msg {
+    struct KeyedMsgName {
+      @key long member1;
+      string member2;
+    };
+  };
+};
+```
+
+<div class="alert alert-info" markdown="1">
+Currently, the message interface format that supports the `@key` annotation is `.idl`.
+Hence, `.msg` and `.srv` do not support the `@key` annotation yet.
+Please refer to [Conversion to IDL](legacy_interface_definition.html) for further information on the equivalence and conversion among them.
+</div>
+
+The general-purpose idl types including primitive types, sequences, strings and structs can be annotated as keys.
+Following are some examples:
+
+| Type                                   | Key Members                  |
+|----------------------------------------|------------------------------|
+| struct NoKey <br/>{ boolean member1;<br/> long member2;<br/> long member3; } | None |
+| struct SimpleKey <br/>{ @key long member1; <br/>long member2; } | member1 |
+| struct ArrayKey <br/>{ @key long member1[3]; } | member1[0] <br> member1[1] <br> member1[2] |
+| struct StringKey <br/>{ @key string member1; <br> long member2} | member1 |
+| struct NestedNoKey <br/>{ SimpleKey member1;<br/> long member2; } | None |
+| struct NestedKey <br/>{ @key SimpleKey member1;<br/> long member2; } | member1.member1 |
+| struct NestedKey2 <br/>{ @key NoKey member1;<br/> long member2; } | member1.member1 <br> member1.member2 <br> member1.member3 |
+| struct ComplexNestedKey <br/>{ @key NestedNoKey member1;<br/> long member2; } | member1.member1.member1 <br> member1.member2 |
 
 #### 8.3.3.1 @default Annotation