Skip to content

Commit 7d3d0de

Browse files
Fernando-A-RochaFernando-A-Rocha
committed
Improve schemas and add event schema and pages
1 parent 73e897b commit 7d3d0de

16 files changed

+402
-128
lines changed

‎.vscode/settings.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
"yaml.schemas": {
33
"schemas/function.yaml": "/functions/**/*",
44
"schemas/element.yaml": "/elements/**/*",
5-
// "schemas/event.yaml": "/events/**/*",
5+
"schemas/event.yaml": "/events/**/*",
66
}
77
}

‎events/.gitkeep

Whitespace-only changes.

‎events/Element/examples/onClientElementInteriorChange.lua

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
local vehicle = createVehicle (411, 0, 0, 3)
2+
setTimer (setElementInterior, 1000, 1, vehicle, 10)
3+
4+
addEventHandler ("onClientElementInteriorChange", vehicle, function (oldInterior, newInterior)
5+
outputChatBox (inspect (source).."'s interior changed from "..oldInterior.." to "..newInterior)
6+
end)

‎events/Element/onClientElementInteriorChange.yaml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: onClientElementInteriorChange
2+
type: client
3+
description: >
4+
This event is triggered when the interior of an element is changed using setElementInterior.
5+
parameters:
6+
- name: oldInterior
7+
type: int
8+
description: An int representing the interior the element was in before.
9+
- name: newInterior
10+
type: int
11+
description: An int representing the interior the element is in now.
12+
source_element:
13+
type: element
14+
description: The source of this event is the element that changed its interior.
15+
examples:
16+
- path: examples/onClientElementInteriorChange.lua
17+
description: >
18+
Demonstrates how to detect and respond to an element's interior change.
19+
Includes vehicle creation and an event handler that reports the interior transition.
20+
notes: []
21+
preview_images: []
22+
version: {}
23+
issues: []
24+
see_also: []

‎schemas/common-defs.yaml

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
$schema: https://json-schema.org/draft/2020-12/schema
2+
$id: common-defs.yaml
3+
title: Common definitions
4+
type: object
5+
$defs:
6+
notes:
7+
type: array
8+
description: List of noteworthy pieces of information for the item.
9+
items:
10+
type: string
11+
12+
meta:
13+
type: array
14+
description: A list of meta properties about the item and it's documentation.
15+
items:
16+
type: object
17+
properties:
18+
needs_checking:
19+
type: string
20+
description: Describe why the item needs checking by another person. What's problematic?
21+
22+
preview_images:
23+
type: array
24+
description: A list of picture assets demonstrating the item.
25+
items:
26+
type: object
27+
required:
28+
- path
29+
properties:
30+
path:
31+
type: string
32+
description: A relative or repository-absolute path to an asset file.
33+
description:
34+
type: string
35+
description: Brief summary of the content in the picture.
36+
37+
version:
38+
type: object
39+
description: Version information when the item got added/deprecated/removed.
40+
properties:
41+
added:
42+
type: string
43+
description: Version when this item was added to MTA.
44+
removed:
45+
type: string
46+
description: Version when this item was removed from MTA.
47+
deprecated:
48+
type: string
49+
description: Version when this item was deprecated in MTA.
50+
replacement:
51+
type: string
52+
description: An optional replacement for this item.
53+
54+
issues:
55+
type: array
56+
description: A list of related issues for this item.
57+
items:
58+
type: object
59+
required:
60+
- id
61+
- description
62+
properties:
63+
id:
64+
type: integer
65+
description: Numeric identifier of the GitHub issue.
66+
description:
67+
type: string
68+
description: Description or summary for this GitHub issue.
69+
70+
examples:
71+
type: array
72+
description: A list of source code examples demonstrating the item.
73+
items:
74+
type: object
75+
required:
76+
- path
77+
properties:
78+
path:
79+
type: string
80+
description: A relative or repository-absolute path to an example source file.
81+
description:
82+
type: string
83+
description: Description for this source code example.
84+
append:
85+
type: boolean
86+
default: false
87+
description: If set to true, this example will be appended to the previous example.
88+
89+
see_also:
90+
type: array
91+
description: |
92+
A list of other categories for further reading.
93+
Every function/event/element will implicitly display it's own category in *See Also*, unless you
94+
introduce this property, then you have to be explicit about it.
95+
items:
96+
type: string
97+
pattern: "^(category):"
98+
uniqueItems: true

‎schemas/element.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
$schema: https://json-schema.org/draft/2020-12/schema
2-
$id: /schemas/element
2+
$id: element.yaml
33
title: Element schema
44
type: object
55
required:

‎schemas/event.yaml

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
$schema: https://json-schema.org/draft/2020-12/schema
2+
$id: event.yaml
3+
title: Event schema
4+
type: object
5+
required:
6+
- name
7+
- type
8+
- description
9+
- source_element
10+
properties:
11+
name:
12+
type: string
13+
description: Exact name of the event.
14+
type:
15+
type: string
16+
description: Type of the event ("client" or "server").
17+
enum:
18+
- client
19+
- server
20+
description:
21+
type: string
22+
description: Description of the event.
23+
parameters:
24+
$ref: '#/$defs/parameters'
25+
source_element:
26+
$ref: '#/$defs/source_element'
27+
notes:
28+
$ref: 'common-defs.yaml#/$defs/notes'
29+
preview_images:
30+
$ref: 'common-defs.yaml#/$defs/preview_images'
31+
version:
32+
$ref: 'common-defs.yaml#/$defs/version'
33+
issues:
34+
$ref: 'common-defs.yaml#/$defs/issues'
35+
examples:
36+
$ref: 'common-defs.yaml#/$defs/examples'
37+
see_also:
38+
$ref: 'common-defs.yaml#/$defs/see_also'
39+
40+
$defs:
41+
source_element:
42+
type: object
43+
properties:
44+
type:
45+
type: string
46+
description: Type of the source element (e.g., "player", "object").
47+
description:
48+
type: string
49+
description: Description of the source element in the event's context.
50+
parameters:
51+
type: array
52+
description: A list of parameters passed to the event handler function.
53+
items:
54+
type: object
55+
required:
56+
- name
57+
- type
58+
- description
59+
properties:
60+
name:
61+
type: string
62+
description: Name of the function parameter.
63+
type:
64+
type: string
65+
description: Type of the function parameter.
66+
description:
67+
type: string
68+
description: Describe the usage, contraints and other useful information about the parameter.

‎schemas/function.yaml

Lines changed: 24 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
$schema: https://json-schema.org/draft/2020-12/schema
2-
$id: /schemas/function
2+
$id: function.yaml
33
title: Function schema
44
type: object
55

@@ -26,6 +26,9 @@ $defs:
2626
name:
2727
type: string
2828
description: Name of the function.
29+
description:
30+
type: string
31+
description: Describes the functionality provided by the function.
2932
pair:
3033
type: string
3134
description: Associates this function with another getter or setter function.
@@ -38,48 +41,26 @@ $defs:
3841
anyOf:
3942
- type: string
4043
- const: true
41-
meta:
42-
$ref: '#/$defs/meta'
43-
description:
44-
type: string
45-
description: Describes the functionality provided by the function.
46-
notes:
47-
type: array
48-
description: List of noteworthy pieces of information for the function.
49-
items:
50-
type: string
51-
preview_images:
52-
$ref: '#/$defs/preview_images'
5344
parameters:
5445
$ref: '#/$defs/parameters'
5546
ignore_parameters:
56-
type: array
57-
description: |
58-
A list of parameters to remove from the parameters list.
59-
You should only use this for shared functions, for example where the client function is
60-
missing a player parameter
61-
items:
62-
type: string
63-
uniqueItems: true
47+
$ref: '#/$defs/ignore_parameters'
6448
returns:
6549
$ref: '#/$defs/returns'
50+
meta:
51+
$ref: 'common-defs.yaml#/$defs/meta'
52+
notes:
53+
$ref: 'common-defs.yaml#/$defs/notes'
54+
preview_images:
55+
$ref: 'common-defs.yaml#/$defs/preview_images'
6656
version:
67-
description: Version information when the function got added/deprecated/removed.
68-
$ref: '#/$defs/version'
57+
$ref: 'common-defs.yaml#/$defs/version'
6958
issues:
70-
$ref: '#/$defs/issues'
59+
$ref: 'common-defs.yaml#/$defs/issues'
7160
examples:
72-
$ref: '#/$defs/examples'
61+
$ref: 'common-defs.yaml#/$defs/examples'
7362
see_also:
74-
type: array
75-
description: |
76-
A list of other categories for further reading.
77-
Every function will implicitly display it's own category in *See Also*, unless you
78-
introduce this property, then you have to be explicit about it.
79-
items:
80-
type: string
81-
pattern: "^(category):"
82-
uniqueItems: true
63+
$ref: 'common-defs.yaml#/$defs/see_also'
8364

8465
oop:
8566
type: object
@@ -114,31 +95,6 @@ $defs:
11495
type: string
11596
description: Name of the constructor.
11697

117-
meta:
118-
type: array
119-
description: A list of meta properties about the function and it's documentation.
120-
items:
121-
type: object
122-
properties:
123-
needs_checking:
124-
type: string
125-
description: Describe why the function needs checking by another person. What's problematic?
126-
127-
preview_images:
128-
type: array
129-
description: A list of picture assets demonstrating the function.
130-
items:
131-
type: object
132-
required:
133-
- path
134-
properties:
135-
path:
136-
type: string
137-
description: A relative or repository-absolute path to an asset file.
138-
description:
139-
type: string
140-
description: Brief summary of the content in the picture.
141-
14298
parameters:
14399
type: array
144100
description: A list of required and optional parameters for the function.
@@ -163,7 +119,15 @@ $defs:
163119
description: |
164120
The default value for this parameter, if none was given in the call to the function.
165121
This property automatically implicitly marks this parameter as optional.
166-
122+
ignore_parameters:
123+
type: array
124+
description: |
125+
A list of parameters to remove from the parameters list.
126+
You should only use this for shared functions, for example where the client function is
127+
missing a player parameter
128+
items:
129+
type: string
130+
uniqueItems: true
167131
returns:
168132
type: object
169133
required:
@@ -187,54 +151,3 @@ $defs:
187151
name:
188152
type: string
189153
description: Name of the return value.
190-
191-
version:
192-
type: object
193-
properties:
194-
added:
195-
type: string
196-
description: Version when this item was added to MTA.
197-
removed:
198-
type: string
199-
description: Version when this item was removed from MTA.
200-
deprecated:
201-
type: string
202-
description: Version when this item was deprecated in MTA.
203-
replacement:
204-
type: string
205-
description: An optional replacement for this item.
206-
207-
issues:
208-
type: array
209-
description: A list of related issues for this function.
210-
items:
211-
type: object
212-
required:
213-
- id
214-
- description
215-
properties:
216-
id:
217-
type: integer
218-
description: Numeric identifier of the GitHub issue.
219-
description:
220-
type: string
221-
description: Description or summary for this GitHub issue.
222-
223-
examples:
224-
type: array
225-
description: A list of source code examples demonstrating the function.
226-
items:
227-
type: object
228-
required:
229-
- path
230-
properties:
231-
path:
232-
type: string
233-
description: A relative or repository-absolute path to an example source file.
234-
description:
235-
type: string
236-
description: Description for this source code example.
237-
append:
238-
type: boolean
239-
default: false
240-
description: If set to true, this example will be appended to the previous example.

0 commit comments

Comments
 (0)