Improve description of srv.send (#1930)

Co-authored-by: Mahati Shankar <[email protected]>
Co-authored-by: René Jeglinsky <[email protected]>

Author: 3 people

guides/providing-services.md

@@ -1123,18 +1123,45 @@ POST .../sue/Foo(2)/Sue.order {"x":3} // bound action
 <br>
 
 
-**Programmatic** usage via **generic APIs** would look like this for Node.js:
+**Programmatic** usage via **generic APIs** for Node.js:
+
+For unbound actions and functions:
+
+```ts
+async function srv.send (
+  event   : string | { event, data?, headers?: object },  
+  data?   : object | any
+)
+return : result of this.dispatch(req)
+```
+
+For bound actions and functions:
+
+```ts
+async function srv.send (
+ event   : string | { event, entity, data?, params?: array of object, headers?: object },
+ entity  : string,
+ data?   : object | any
+)
+return : result of this.dispatch(req)
+```
+
+-  `event` is a name of a custom action or function
+-  `entity` is a name of an entity
+-  `params` are keys of the entity instance
+
+Programmatic usage would look like this for Node.js:
 
 ```js
   const srv = await cds.connect.to('Sue')
   // unbound actions/functions
   await srv.send('sum',{x:1,y:2})
   await srv.send('stock',{id:2})
   await srv.send('add',{x:11,to:2})
-  // bound actions/functions
+  // actions/functions bound to collection
   await srv.send('getStock','Foo',{id:2})
-  //for passing the params property, use this syntax
-  await srv.send({ event: 'order', entity: 'Foo', data: {x:3}, params: [2]})
+  // for actions/functions bound to entity instance, use this syntax
+  await srv.send({ event: 'order', entity: 'Foo', data: {x:3}, params: [{id:2}]})
 ```
 
 > Note: Always pass the target entity name as second argument for bound actions/functions.

node.js/core-services.md

@@ -796,9 +796,11 @@ return : result of this.dispatch(req)
 
 Use this method to send synchronous requests to a service for execution.
 
--  `method` can be an HTTP method, or a name of a custom action or function
+-  `method` is an HTTP method
 -  `path` can be an arbitrary URL, starting with a leading `'/'`, it is passed to a service without any modification as a string
 
+To call bound / unbound actions and functions from the service, further variants of `srv.send` are additionally supported, as described in the section [Calling Actions / Functions](../guides/providing-services#calling-actions-functions). Basically, use the action or function name instead of the HTTP method.
+
 Examples:
 
 ```js