Add introductory paragraph to Links section in docs of each event (#278)

magnusbaeck · web-flow · commit 41d31d591981 · 2021-10-12T14:30:03.000+02:00
Previously the Links section only had subsections for the valid link
types and no easy way to find information on what a link object looks
like. The new introductory paragraph explains both what the section
contains and links to the-links-object.md.
diff --git a/eiffel-vocabulary/EiffelActivityCanceledEvent.md b/eiffel-vocabulary/EiffelActivityCanceledEvent.md
@@ -25,6 +25,9 @@ __Required:__ No
 __Description:__ Any human readable information as to the reason for dequeueing.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### ACTIVITY_EXECUTION
 __Required:__ Yes  
 __Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md)  
diff --git a/eiffel-vocabulary/EiffelActivityFinishedEvent.md b/eiffel-vocabulary/EiffelActivityFinishedEvent.md
@@ -67,6 +67,9 @@ __Required:__ Yes
 __Description:__ The URI at which the log can be retrieved.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### ACTIVITY_EXECUTION
 __Required:__ Yes  
 __Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md)  
diff --git a/eiffel-vocabulary/EiffelActivityStartedEvent.md b/eiffel-vocabulary/EiffelActivityStartedEvent.md
@@ -50,6 +50,9 @@ __Required:__ Yes
 __Description:__ The URI at which the log can be retrieved.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### ACTIVITY_EXECUTION
 __Required:__ Yes  
 __Legal targets:__ [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md)  
diff --git a/eiffel-vocabulary/EiffelActivityTriggeredEvent.md b/eiffel-vocabulary/EiffelActivityTriggeredEvent.md
@@ -59,6 +59,9 @@ __Legal values:__ MANUAL, SEMI_AUTOMATED, AUTOMATED, OTHER
 __Description:__ The type of execution (often related to, but ultimately separate from, __data.triggers.type__).
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### CAUSE
 __Required:__ No  
 __Legal targets:__ Any  
diff --git a/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md b/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md
@@ -41,6 +41,9 @@ __Legal values:__ MINOR, MAJOR, CRITICAL, BLOCKER, CLOSED, CANCELED
 __Description:__ The severity of the announcement. The CLOSED and CANCELED values SHOULD only be used when following up a previous announcement, i.e. in conjunction with a __MODIFIED_ANNOUNCEMENT__ link.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### MODIFIED_ANNOUNCEMENT
 __Required:__ No  
 __Legal targets:__ [EiffelAnnouncementPublishedEvent](../eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md)  
diff --git a/eiffel-vocabulary/EiffelArtifactCreatedEvent.md b/eiffel-vocabulary/EiffelArtifactCreatedEvent.md
@@ -73,6 +73,9 @@ __Required:__ No
 __Description:__ Any (colloquial) name of the artifact. Unlike __data.identity__, this is not intended as an unambiguous identifier of the artifact, but as a descriptive and human readable name.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### COMPOSITION
 __Required:__ No  
 __Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)  
diff --git a/eiffel-vocabulary/EiffelArtifactPublishedEvent.md b/eiffel-vocabulary/EiffelArtifactPublishedEvent.md
@@ -45,6 +45,9 @@ __Required:__ Yes
 __Description:__ The URI at which the artifact can be retrieved.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### ARTIFACT
 __Required:__ Yes  
 __Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md)  
diff --git a/eiffel-vocabulary/EiffelArtifactReusedEvent.md b/eiffel-vocabulary/EiffelArtifactReusedEvent.md
@@ -23,6 +23,9 @@ The event has no data members, but solely relies on its two required link types
 ## Data Members
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### COMPOSITION
 __Required:__ Yes  
 __Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)  
diff --git a/eiffel-vocabulary/EiffelCompositionDefinedEvent.md b/eiffel-vocabulary/EiffelCompositionDefinedEvent.md
@@ -30,6 +30,9 @@ __Required:__ No
 __Description:__ The version of the composition, if any. This is in a sense redundant, as relationships between compositions can be tracked via the __PREVIOUS_VERSION__ link type, but can be used for improved clarity and semantics.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### ELEMENT
 __Required:__ No  
 __Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md), 
diff --git a/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md b/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md
@@ -61,6 +61,9 @@ __Required:__ No
 __Description:__ Any group, such as a development team, committee or test group, to which the issuer belongs.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### SUBJECT
 __Required:__ Yes  
 __Optional in:__ None  
diff --git a/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md b/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md
@@ -57,6 +57,9 @@ __Required:__ No
 __Description:__ A URI identifying the environment description. This is the catch-all method of environment descriptions. Eiffel does not concern itself with the format or nature of the description, but merely points to its location.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### PREVIOUS_VERSION
 __Required:__ No  
 __Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md)  
diff --git a/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md b/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md
@@ -47,6 +47,9 @@ __Required:__ No
 __Description:__ A version context which other events can relate to. This member SHOULD be used in tandem with one of the other optional members - a version by itself is not very informative.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### CAUSE
 __Required:__ No  
 __Legal targets:__ Any  
diff --git a/eiffel-vocabulary/EiffelIssueDefinedEvent.md b/eiffel-vocabulary/EiffelIssueDefinedEvent.md
@@ -63,6 +63,8 @@ following __data.uri__.
 
 ## Links
 
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### CAUSE
 __Required:__ No  
 __Legal targets:__ Any  
diff --git a/eiffel-vocabulary/EiffelIssueVerifiedEvent.md b/eiffel-vocabulary/EiffelIssueVerifiedEvent.md
@@ -23,6 +23,9 @@ EiffelIssueVerifiedEvent has no data members, instead relying on its required li
 ## Data Members
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### SUCCESSFUL_ISSUE
 __Required:__ No  
 __Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md)  
diff --git a/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md b/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md
@@ -177,6 +177,9 @@ __Required:__ Yes
 __Description:__ The URI of the repo.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### BASE
 __Required:__ No  
 __Legal targets:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)  
diff --git a/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md b/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md
@@ -144,6 +144,9 @@ __Required:__ Yes
 __Description:__ The URI of the repo.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### CHANGE
 __Required:__ No  
 __Legal targets:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)  
diff --git a/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md b/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md
@@ -25,6 +25,9 @@ __Required:__ No
 __Description:__ Any human readable information as to the reason for dequeueing.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### TEST_CASE_EXECUTION
 __Required:__ Yes  
 __Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md)  
diff --git a/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md b/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md
@@ -94,6 +94,9 @@ __Required:__ Yes
 __Description:__ The URI at which the log can be retrieved.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### TEST_CASE_EXECUTION
 __Required:__ Yes  
 __Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md)  
diff --git a/eiffel-vocabulary/EiffelTestCaseStartedEvent.md b/eiffel-vocabulary/EiffelTestCaseStartedEvent.md
@@ -50,6 +50,9 @@ __Required:__ Yes
 __Description:__ The URI at which the log can be retrieved.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### TEST_CASE_EXECUTION
 __Required:__ Yes  
 __Legal targets:__ [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md)  
diff --git a/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md b/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md
@@ -94,6 +94,9 @@ __Required:__ Yes
 __Description:__ The value of the parameter.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### IUT
 __Required:__ Yes  
 __Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
diff --git a/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md b/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md
@@ -128,6 +128,9 @@ __Required:__ Yes
 __Description:__ The UUID of the dependent execution (__data.batches.recipes.id__), i.e. the execution that shall be performed only after that of the dependency.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### CAUSE
 __Required:__ No  
 __Legal targets:__ Any  
diff --git a/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md b/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md
@@ -77,6 +77,9 @@ __Required:__ Yes
 __Description:__ The URI at which the log can be retrieved.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### TEST_SUITE_EXECUTION
 __Required:__ Yes  
 __Legal targets:__ [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)  
diff --git a/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md b/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md
@@ -63,6 +63,9 @@ __Required:__ Yes
 __Description:__ The URI at which the log can be retrieved.
 
 ## Links
+
+This section describes which link types are valid for this event type. For details on how to express the link objects themselves see [The Links Object](../eiffel-syntax-and-usage/the-links-object.md).
+
 ### TERC
 __Required:__ No  
 __Legal targets:__ [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)  
