Async descriptions

SAP · Sep 1, 2023 · a683229 · a683229
1 parent c309707
commit a683229
Show file tree

Hide file tree

Showing 3 changed files with 39 additions and 21 deletions.
diff --git a/vocabularies/Common.json b/vocabularies/Common.json
@@ -1350,10 +1350,23 @@
         "@Common.Experimental": true,
         "@Core.Description": "Template for functions that compute AI-based recommendations in asynchronous OData requests",
         "$Parameter": [
-          { "$Name": "Entity", "$Type": "Edm.EntityType" },
-          { "$Name": "Targets", "$Collection": true, "@Core.IsURL": true }
+          {
+            "$Name": "Entity",
+            "$Type": "Edm.EntityType",
+            "@Core.Description": "See parameter `Entity` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)"
+          },
+          {
+            "$Name": "Targets",
+            "$Collection": true,
+            "@Core.IsURL": true,
+            "@Core.Description": "See parameter `Targets` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)"
+          }
         ],
-        "$ReturnType": { "$Collection": true, "$Type": "Common.PropertyRecommendationType" }
+        "$ReturnType": {
+          "$Collection": true,
+          "$Type": "Common.PropertyRecommendationType",
+          "@Core.Description": "See return type in [`Template_RecommendationsRetrievalFunction`](#Template_RecommendationsRetrievalFunction)"
+        }
       }
     ],
     "PropertyRecommendationType": {

diff --git a/vocabularies/Common.md b/vocabularies/Common.md
@@ -111,7 +111,7 @@ Term|Type|Description
 [PrimitivePropertyPath](./Common.xml#L1446:~:text=<Term%20Name="-,PrimitivePropertyPath,-") *([Experimental](Common.md#Experimental))*|[Tag](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Tag)|<a name="PrimitivePropertyPath"></a>A term or term property with this tag whose type is (a collection of) `Edm.PropertyPath` MUST resolve to a primitive structural property
 [WebSocketBaseURL](./Common.xml#L1451:~:text=<Term%20Name="-,WebSocketBaseURL,-") *([Experimental](Common.md#Experimental))*|URL|<a name="WebSocketBaseURL"></a>Base URL for WebSocket connections
 [RecommendationsFunction](./Common.xml#L1457:~:text=<Term%20Name="-,RecommendationsFunction,-") *([Experimental](Common.md#Experimental))*|[QualifiedName](#QualifiedName)|<a name="RecommendationsFunction"></a>Qualified name of a function that computes AI-based recommendations for entities of the annotated type (see [template](#Template_RecommendationsFunction) and [template for asynchronous OData requests](#Template_AsyncRecommendationsFunction))
-[RecommendationsRole](./Common.xml#L1541:~:text=<Term%20Name="-,RecommendationsRole,-") *([Experimental](Common.md#Experimental))*|[RecommendationsRoleType](#RecommendationsRoleType)|<a name="RecommendationsRole"></a>Role of this property or parameter regarding AI-based recommendations
+[RecommendationsRole](./Common.xml#L1546:~:text=<Term%20Name="-,RecommendationsRole,-") *([Experimental](Common.md#Experimental))*|[RecommendationsRoleType](#RecommendationsRoleType)|<a name="RecommendationsRole"></a>Role of this property or parameter regarding AI-based recommendations
 
 
 ## Functions
@@ -153,9 +153,9 @@ Template for functions that compute AI-based recommendations in asynchronous ODa
 
 Parameter|Type|Description
 :--------|:---|:----------
-**[Entity](./Common.xml#L1506:~:text=<Function%20Name="-,Template_AsyncRecommendationsFunction,-")**|EntityType|**Binding parameter**
-[Targets](./Common.xml#L1507:~:text=<Function%20Name="-,Template_AsyncRecommendationsFunction,-")|\[URL\]|
-[&rarr;](./Common.xml#L1510:~:text=<Function%20Name="-,Template_AsyncRecommendationsFunction,-")|\[[PropertyRecommendationType](#PropertyRecommendationType)\]|
+**[Entity](./Common.xml#L1506:~:text=<Function%20Name="-,Template_AsyncRecommendationsFunction,-")**|EntityType|**Binding parameter:** See parameter `Entity` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)
+[Targets](./Common.xml#L1509:~:text=<Function%20Name="-,Template_AsyncRecommendationsFunction,-")|\[URL\]|See parameter `Targets` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)
+[&rarr;](./Common.xml#L1513:~:text=<Function%20Name="-,Template_AsyncRecommendationsFunction,-")|\[[PropertyRecommendationType](#PropertyRecommendationType)\]|See return type in [`Template_RecommendationsRetrievalFunction`](#Template_RecommendationsRetrievalFunction)
 
 
 <a name="TextFormatType"></a>
@@ -476,31 +476,31 @@ Use terms [Aggregation.RecursiveHierarchy](https://github.com/oasis-tcs/odata-vo
 User ID
 
 <a name="PropertyRecommendationType"></a>
-## [PropertyRecommendationType](./Common.xml#L1512:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-") *([Experimental](Common.md#Experimental))*
+## [PropertyRecommendationType](./Common.xml#L1517:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-") *([Experimental](Common.md#Experimental))*
 
 
 Property|Type|Description
 :-------|:---|:----------
-[target](./Common.xml#L1514:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|URL|URL (relative to the URL of the recommendations function request) addressing a property [OData-URL, section 4.6] that is targeted by this recommendation<br>The request `SalesOrder('A')/ns.RecommendationsFunction?Targets=...` might retrieve a recommendation with `"target": "Items(10)/Product"`.
-[value](./Common.xml#L1522:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|String|Recommended value, converted to string
-[text](./Common.xml#L1525:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|String?|Description of the recommended value
-[alternatives](./Common.xml#L1528:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|\[[AlternativeRecommendationType](#AlternativeRecommendationType)\]|Alternative recommendations
+[target](./Common.xml#L1519:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|URL|URL (relative to the URL of the recommendations function request) addressing a property [OData-URL, section 4.6] that is targeted by this recommendation<br>The request `SalesOrder('A')/ns.RecommendationsFunction?Targets=...` might retrieve a recommendation with `"target": "Items(10)/Product"`.
+[value](./Common.xml#L1527:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|String|Recommended value, converted to string
+[text](./Common.xml#L1530:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|String?|Description of the recommended value
+[alternatives](./Common.xml#L1533:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|\[[AlternativeRecommendationType](#AlternativeRecommendationType)\]|Alternative recommendations
 
 <a name="AlternativeRecommendationType"></a>
-## [AlternativeRecommendationType](./Common.xml#L1532:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-") *([Experimental](Common.md#Experimental))*
+## [AlternativeRecommendationType](./Common.xml#L1537:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-") *([Experimental](Common.md#Experimental))*
 
 
 Property|Type|Description
 :-------|:---|:----------
-[value](./Common.xml#L1534:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-")|String|Alternatively recommended value, converted to string
-[score](./Common.xml#L1537:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-")|Decimal?|Score of the alternatively recommended value
+[value](./Common.xml#L1539:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-")|String|Alternatively recommended value, converted to string
+[score](./Common.xml#L1542:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-")|Decimal?|Score of the alternatively recommended value
 
 <a name="RecommendationsRoleType"></a>
-## [RecommendationsRoleType](./Common.xml#L1545:~:text=<EnumType%20Name="-,RecommendationsRoleType,-") *([Experimental](Common.md#Experimental))*
+## [RecommendationsRoleType](./Common.xml#L1550:~:text=<EnumType%20Name="-,RecommendationsRoleType,-") *([Experimental](Common.md#Experimental))*
 
 
 Flag Member|Value|Description
 :-----|----:|:----------
-[Input](./Common.xml#L1547:~:text=<EnumType%20Name="-,RecommendationsRoleType,-")|1|The property is input for some recommendation
-[Output](./Common.xml#L1550:~:text=<EnumType%20Name="-,RecommendationsRoleType,-")|2|The property or parameter is the target of some recommendation
-[Required](./Common.xml#L1553:~:text=<EnumType%20Name="-,RecommendationsRoleType,-")|4|The property is mandatory for recommendations to be requested
+[Input](./Common.xml#L1552:~:text=<EnumType%20Name="-,RecommendationsRoleType,-")|1|The property is input for some recommendation
+[Output](./Common.xml#L1555:~:text=<EnumType%20Name="-,RecommendationsRoleType,-")|2|The property or parameter is the target of some recommendation
+[Required](./Common.xml#L1558:~:text=<EnumType%20Name="-,RecommendationsRoleType,-")|4|The property is mandatory for recommendations to be requested
diff --git a/vocabularies/Common.xml b/vocabularies/Common.xml
@@ -1503,11 +1503,16 @@ If the request succeeds the response will contain a JSON body of `Content-Type:
       <Function Name="Template_AsyncRecommendationsFunction" IsBound="true">
         <Annotation Term="Common.Experimental" />
         <Annotation Term="Core.Description" String="Template for functions that compute AI-based recommendations in asynchronous OData requests" />
-        <Parameter Name="Entity" Type="Edm.EntityType" Nullable="false" />
+        <Parameter Name="Entity" Type="Edm.EntityType" Nullable="false">
+          <Annotation Term="Core.Description" String="See parameter `Entity` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)" />
+        </Parameter>
         <Parameter Name="Targets" Type="Collection(Edm.String)" Nullable="false">
           <Annotation Term="Core.IsURL" />
+          <Annotation Term="Core.Description" String="See parameter `Targets` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)" />
         </Parameter>
-        <ReturnType Type="Collection(Common.PropertyRecommendationType)" Nullable="false" />
+        <ReturnType Type="Collection(Common.PropertyRecommendationType)" Nullable="false">
+          <Annotation Term="Core.Description" String="See return type in [`Template_RecommendationsRetrievalFunction`](#Template_RecommendationsRetrievalFunction)" />
+        </ReturnType>
       </Function>
       <ComplexType Name="PropertyRecommendationType">
         <Annotation Term="Common.Experimental" />