godotengine
/
godot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve JSON-related documentation 

This closes https://github.com/godotengine/godot-docs/issues/3848.
This commit is contained in:
Hugo Locurcio 2020-07-31 09:53:04 +02:00
parent 718db9b396
commit 930e10ffff
3 changed files with 22 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/classes/JSON.xml
View File

@ -15,7 +15,7 @@
<argument index="0" name="json" type="String">
</argument>
<description>
Parses a JSON encoded string and returns a [JSONParseResult] containing the result.
Parses a JSON-encoded string and returns a [JSONParseResult] containing the result.
</description>
</method>
<method name="print">
@ -29,6 +29,7 @@
</argument>
<description>
Converts a [Variant] var to JSON text and returns the result. Useful for serializing data to store or send over the network.
[b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, converting a Variant to JSON text will convert all numerical values to [float] types.
</description>
</method>
</methods>

10
doc/classes/JSONParseResult.xml
View File

@ -15,21 +15,21 @@
The error type if the JSON source was not successfully parsed. See the [enum Error] constants.
</member>
<member name="error_line" type="int" setter="set_error_line" getter="get_error_line" default="-1">
The line number where the error occurred if JSON source was not successfully parsed.
The line number where the error occurred if the JSON source was not successfully parsed.
</member>
<member name="error_string" type="String" setter="set_error_string" getter="get_error_string" default="&quot;&quot;">
The error message if JSON source was not successfully parsed. See the [enum Error] constants.
The error message if the JSON source was not successfully parsed. See the [enum Error] constants.
</member>
<member name="result" type="Variant" setter="set_result" getter="get_result">
A [Variant] containing the parsed JSON. Use [method @GDScript.typeof] or the [code]is[/code] keyword to check if it is what you expect. For example, if the JSON source starts with curly braces ([code]{}[/code]), a [Dictionary] will be returned. If the JSON source starts with braces ([code][][/code]), an [Array] will be returned.
[b]Note:[/b] The JSON specification does not define integer or float types, but only a number type. Therefore, parsing a JSON text will convert all numerical values to float types.
A [Variant] containing the parsed JSON. Use [method @GDScript.typeof] or the [code]is[/code] keyword to check if it is what you expect. For example, if the JSON source starts with curly braces ([code]{}[/code]), a [Dictionary] will be returned. If the JSON source starts with brackets ([code][][/code]), an [Array] will be returned.
[b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, parsing a JSON text will convert all numerical values to [float] types.
[b]Note:[/b] JSON objects do not preserve key order like Godot dictionaries, thus, you should not rely on keys being in a certain order if a dictionary is constructed from JSON. In contrast, JSON arrays retain the order of their elements:
[codeblock]
var p = JSON.parse('["hello", "world", "!"]')
if typeof(p.result) == TYPE_ARRAY:
print(p.result[0]) # Prints "hello"
else:
print("unexpected results")
push_error("Unexpected results.")
[/codeblock]
</member>
</members>

25
modules/gdscript/doc_classes/@GDScript.xml
View File

@ -735,16 +735,17 @@
<argument index="0" name="json" type="String">
</argument>
<description>
Parse JSON text to a Variant (use [method typeof] to check if it is what you expect).
Be aware that the JSON specification does not define integer or float types, but only a number type. Therefore, parsing a JSON text will convert all numerical values to [float] types.
Note that JSON objects do not preserve key order like Godot dictionaries, thus you should not rely on keys being in a certain order if a dictionary is constructed from JSON. In contrast, JSON arrays retain the order of their elements:
Parse JSON text to a Variant. (Use [method typeof] to check if the Variant's type is what you expect.)
[b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, parsing a JSON text will convert all numerical values to [float] types.
[b]Note:[/b] JSON objects do not preserve key order like Godot dictionaries, thus, you should not rely on keys being in a certain order if a dictionary is constructed from JSON. In contrast, JSON arrays retain the order of their elements:
[codeblock]
p = parse_json('["a", "b", "c"]')
if typeof(p) == TYPE_ARRAY:
print(p[0]) # Prints a
var p = JSON.parse('["hello", "world", "!"]')
if typeof(p.result) == TYPE_ARRAY:
print(p.result[0]) # Prints "hello"
else:
print("unexpected results")
push_error("Unexpected results.")
[/codeblock]
See also [JSON] for an alternative way to parse JSON text.
</description>
</method>
<method name="polar2cartesian">
@ -1220,12 +1221,16 @@
<argument index="0" name="var" type="Variant">
</argument>
<description>
Converts a Variant [code]var[/code] to JSON text and return the result. Useful for serializing data to store or send over the network.
Converts a [Variant] [code]var[/code] to JSON text and return the result. Useful for serializing data to store or send over the network.
[codeblock]
# Both numbers below are integers.
a = { "a": 1, "b": 2 }
b = to_json(a)
print(b) # {"a":1, "b":2}
# Both numbers above are floats, even if they display without any decimal places.
[/codeblock]
[b]Note:[/b] The JSON specification does not define integer or float types, but only a [i]number[/i] type. Therefore, converting a [Variant] to JSON text will convert all numerical values to [float] types.
See also [JSON] for an alternative way to convert a [Variant] to JSON text.
</description>
</method>
<method name="type_exists">
@ -1268,9 +1273,9 @@
j = to_json([1, 2, 3])
v = validate_json(j)
if not v:
print("valid")
print("Valid JSON.")
else:
prints("invalid", v)
push_error("Invalid JSON: " + v)
[/codeblock]
</description>
</method>