Skip to content

Commit

Permalink
fix: Properly document context params (rdkcentral#75)
Browse files Browse the repository at this point in the history 
* fix: Properly document context params

* fix: Remove unused code
  • Loading branch information
@jlacivita
jlacivita authored Nov 10, 2022
1 parent d41dac7 commit 325858c
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 120 deletions.
37 changes: 23 additions & 14 deletions src/template/markdown/methods/polymorphic-property.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,26 @@ ${method.description}

${method.1}

To get the value, call the method with no parameters:
To get the value of `${method.name}` call the method like this:

${if.javascript}

```typescript
function ${method.name}(): Promise<${method.result.type}>
${method.signature}
```

${end.if.javascript}

${if.params}

Parameters:

| Param | Type | Required | Summary |
| ---------------------- | -------------------- | ------------------------ | ----------------------- |
| `${method.param.name}` | ${method.param.type} | ${method.param.required} | ${method.param.summary} ${method.param.constraints} |

${end.if.params}

Promise resolution:

${method.result}
Expand Down Expand Up @@ -56,12 +66,12 @@ ${end.example}
${end.method}

${method.2}
To set the value, pass in the new value as the only parameter:
To set the value of `${method.name}` call the method like this:

${if.javascript}

```typescript
function ${method.name}(${method.params}): Promise<void>
${method.signature}
```

${end.if.javascript}
Expand Down Expand Up @@ -90,9 +100,6 @@ JavaScript:
import { ${module} } from '${package.name}'

${module}.${method.name}(${example.params})
.then(${method.result.name} => {
// property value has been set
})
```

${end.if.javascript}
Expand All @@ -118,12 +125,12 @@ ${end.example}
${end.method}

${method.3}
To subscribe to notifications when the value changes, pass a function as the only parameter:
To subscribe to notifications when the value changes, call the method like this:

${if.javascript}

```typescript
function ${method.name}(subscriber: (${method.params}) => void): Promise<boolean>
function ${method.name} (${method.params} ${if.params}, ${end.if.params}subscriber: (${method.result.name}) => void): Promise<listenerId>
```

${end.if.javascript}
Expand All @@ -132,7 +139,9 @@ Parameters:

| Param | Type | Required | Summary |
| ---------------------- | -------------------- | ------------------------ | ----------------------- |
| `subscriber` | `Function` | Yes | A callback that gets invoked when the value for ${method.name} changes |
| `${method.param.name}` | ${method.param.type} | ${method.param.required} | ${method.param.summary} ${method.param.constraints} |
| `subscriber` | `function` | Yes | Callback to execute when the value changes. |


Promise resolution:

Expand All @@ -144,7 +153,7 @@ Callback parameters:

| Param | Type | Required | Summary |
| ---------------------- | -------------------- | ------------------------ | ----------------------- |
| `${method.param.name}` | ${method.param.type} | Yes | ${method.param.summary} ${method.param.constraints} |
| `${method.result.name}` | `${event.result.type}` | Yes | ${method.result.summary} |

**Examples**

Expand All @@ -157,15 +166,15 @@ JavaScript:
```javascript
import { ${module} } from '${package.name}'

${module}.${method.name}(${method.paramNames} => {
${module}.${method.name}(${method.paramNames} ${if.params}, ${end.if.params}(value) => {
// property value was changed
console.log(${method.paramNames})
console.log(value)
}).then(listenerId => {
// you can clear this listener w/ ${module}.clear(listenerId)
})
```

value of `${method.paramNames}`:
value of `value`:

```javascript
${example.result}
Expand Down
126 changes: 20 additions & 106 deletions util/docs/macros/index.mjs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,7 @@ function insertMacros(data = '', moduleJson = {}, templates = {}, schemas = {},
// change the template
event.tags.find(t => t.name === 'event').name = 'additional-event'
// drop the ListenerResponse result type
event.result.schema = (event.result.schema.oneOf || event.result.schema.anyOf)[1]
event.result.schema = (event.result.schema.oneOf || event.result.schema.anyOf).pop()
additionalStr += insertMethodMacros(match[0], event, moduleJson, schemas, templates, options)
})
data = data.replace(regex, additionalStr)
Expand Down Expand Up @@ -529,80 +529,25 @@ function insertMethodMacros(data, method, moduleJson = {}, schemas = {}, templat
return result
}

function generatePropertySignatures (m) {
function generatePropertySignatures (m, json) {
let signatures = [m]
if (hasTag(m, 'property') && !hasTag(m, 'property:immutable') && !hasTag(m, 'property:readonly')) {
signatures.push({
name: m.name,
summary: 'Set value for ' + m.summary,
tags: [
{
name: 'property-set'
}
],
// setter takes the getters result
params: [
{
...m.result,
name: 'value',
required: true
}
],
result: {
name: "response",
summary: "",
schema: {
const: null
}
},
examples: [
{
name: "",
params: [
{
name: "value",
value: m.examples[0].result.value
}
],
result: {
name: "Default Result",
value: null
}
}
]
})
} else {
signatures.push(null)

const setter = json.methods.find(m => m.tags && m.tags.find(t => t['x-setter-for']) && m.tags.find(t => t['x-setter-for'] === signatures[0].name))
const subscriber = json.methods.find(m => m.tags && m.tags.find(t => t['x-alternative']) && m.tags.find(t => t['x-alternative'] === signatures[0].name))

if (setter) {
setter.tags = setter.tags.filter(t => t.name !== 'rpc-only')
setter.name = m.name
signatures.push(setter)
}
if ((hasTag(m, 'property') || hasTag(m, 'property:readonly')) && !hasTag(m, 'property:immutable')) {
const examples = []
m.examples.forEach(e => examples.push(JSON.parse(JSON.stringify(e))))
examples.forEach(e => { e.params = [ { name: m.result.name, value: e.result.value } ]; e.result = { name: 'listenerId', value: 1 }; })

signatures.push({
name: m.name,
summary: 'Subscribe to value for ' + m.summary,
tags: [{
name: 'property-subscribe'
}],
params: [
{
...m.result,
required: true
}
],
result: {
name: "listenerId",
summary: "",
schema: {
type: "integer"
}
},
examples: m.examples
})
} else {
signatures.push(null)

if (subscriber) {
subscriber.tags = subscriber.tags.filter(t => t.name !== 'rpc-only')
subscriber.name = m.name
subscriber.params = m.params
signatures.push(subscriber)
}

return signatures
}

Expand All @@ -612,7 +557,7 @@ function iterateSignatures(data, method, moduleJson = {}, schemas = {}, template
const module = moduleJson.info.title
let signatures = [method]
if (hasTag(method, 'property') || hasTag(method, 'property:readonly') || hasTag(method, 'property:immutable')) {
signatures = generatePropertySignatures(method)
signatures = generatePropertySignatures(method, moduleJson)
}

if (method.tags && method.tags.find(t => t.name === 'polymorphic-pull')) {
Expand Down Expand Up @@ -742,6 +687,7 @@ function insertSignatureMacros(block, sig, moduleJson = {}, schemas = {}, templa
.replace(/\$\{method.result.summary\}/g, sig.result.summary)
.replace(/\$\{method.result.link\}/g, getSchemaType(moduleJson, sig.result, schemas, {title: true, link: true, asPath: options.asPath, baseUrl: options.baseUrl}))
.replace(/\$\{method.result.type\}/g, getSchemaType(moduleJson, sig.result, schemas, {title: true, asPath: options.asPath, baseUrl: options.baseUrl}))
.replace(/\$\{event.result.type\}/, getSchemaType(moduleJson, (sig.result.schema.anyOf || [sig.result.schema]).pop(), schemas, { event: true, description: sig.result.summary, asPath: options.asPath, baseUrl: options.baseUrl })) //getType(method.result, true))
.replace(/\$\{method.result\}/g, getSchemaTypeTable(moduleJson, sig.result, schemas, { description: sig.result.summary, title: true, asPath: options.asPath, baseUrl: options.baseUrl}))

return block
Expand Down Expand Up @@ -814,7 +760,7 @@ function insertEventMacros(data = '', methods = [], moduleJson = {}, schemas = {
.replace(/\$\{event.description\}/, method.description)
.replace(/\$\{event.result.name\}/, method.result.name)
.replace(/\$\{event.result.summary\}/, method.result.summary)
.replace(/\$\{event.result.type\}/, getSchemaTypeTable(moduleJson, method.result, schemas, { event: true, description: method.result.summary, asPath: options.asPath, baseUrl: options.baseUrl })) //getType(method.result, true))
.replace(/\$\{event.result.type\}/, getSchemaTypeTable(moduleJson, method.result.schema.anyOf.pop(), schemas, { event: true, description: method.result.summary, asPath: options.asPath, baseUrl: options.baseUrl })) //getType(method.result, true))

let match, regex = /[\# \t]*?\$\{example\.[a-zA-Z]+\}.*?\$\{end.example\}/s
while (match = method_data.match(regex)) {
Expand Down Expand Up @@ -1017,12 +963,6 @@ function generateJavaScriptExampleResult(example) {
}

function generateRPCExample(example, m, moduleJson = {}) {
if (m.tags && m.tags.filter(t => (t.name === 'property-subscribe')).length) {
return generatePropertyChangedRPCExample(example, m, moduleJson)
}
else if (m.tags && m.tags.filter(t => (t.name === 'property-set')).length) {
return generatePropertySetRPCExample(example, m, moduleJson.info.title)
}
let request = {
"jsonrpc": "2.0",
"id": 1,
Expand All @@ -1040,32 +980,6 @@ function generateRPCExample(example, m, moduleJson = {}) {
return JSON.stringify(request, null, ' ')
}

function generatePropertyChangedRPCExample(example, m, module) {
let request = {
jsonrpc: "2.0",
id: 1,
"method": `${getTitle(module).toLowerCase()}.on${m.name.substr(0, 1).toUpperCase()}${m.name.substr(1)}Changed`,
"params": {
listen: true
},
}

return JSON.stringify(request, null, ' ')
}

function generatePropertySetRPCExample(example, m, module) {
let request = {
jsonrpc: "2.0",
id: 1,
"method": `${module.toLowerCase()}.set${m.name.substr(0, 1).toUpperCase()}${m.name.substr(1)}`,
"params": {
value: example.params[0].value
},
}

return JSON.stringify(request, null, ' ')
}

function generateRPCExampleResult(example) {
return JSON.stringify({
"jsonrpc": "2.0",
Expand Down

0 comments on commit 325858c

Please sign in to comment.