{{ alias.name | escape }} = {{ alias.target_type_html }}
{{ alias.name | escape }} = {{ alias.target_type_html }}
{{ alias.description }}
{%- if alias.examples.size > 0 -%} diff --git a/refdoc.py b/refdoc.py index e4f75e263..623191d6d 100644 --- a/refdoc.py +++ b/refdoc.py @@ -363,29 +363,22 @@ def prepare_lua_v2(api, current_page="", targets=None): } member_names = list(documented_members) if not member_names: - prefixes = (enum_name + "_", enum_name + ".") - member_names = sorted( - name for name in constants if name.startswith(prefixes)) + raise ValueError( + "enum %s must declare at least one explicit member" + % enum_name) resolved_members = [] for member_name in member_names: constant = constants.get(member_name) if constant: - previous_enum = constant.get("enum") - if previous_enum and previous_enum != enum_name: - raise ValueError( - "constant %s belongs to both %s and %s" - % (member_name, previous_enum, enum_name)) - constant["enum"] = enum_name - constant["is_enum_member"] = True - constant["value_type"] = enum_name + raise ValueError( + "enum %s member %s is also declared as a standalone " + "constant" % (enum_name, member_name)) documented = documented_members.get(member_name, {}) resolved_members.append({ "name": member_name, "doc": _link_lua_type_spans(( documented.get("doc") - or (constant or {}).get("description") - or (constant or {}).get("brief") or ""), current_page, targets), }) enum["members"] = resolved_members diff --git a/tests/test_api_lua_v2_rendering.rb b/tests/test_api_lua_v2_rendering.rb new file mode 100644 index 000000000..75d9f4a9d --- /dev/null +++ b/tests/test_api_lua_v2_rendering.rb @@ -0,0 +1,99 @@ +# frozen_string_literal: true + +require "fileutils" +require "json" +require "jekyll" +require "minitest/autorun" +require "tmpdir" + +class ApiLuaV2RenderingTest < Minitest::Test + ROOT = File.expand_path("..", __dir__) + INCLUDES = %w[ + api_lua_v2.html + api_lua_v2_parameters.html + api_lua_v2_signature.html + api_lua_v2_summary.html + ref_anchor_target.html + ref_anchorlink.html + ].freeze + + def test_member_markup_and_long_alias_signature + Dir.mktmpdir("defold-api-lua-v2-test") do |directory| + source = File.join(directory, "source") + destination = File.join(directory, "site") + includes = File.join(source, "_includes") + data = File.join(source, "_data") + FileUtils.mkdir_p([includes, data]) + + INCLUDES.each do |name| + FileUtils.cp( + File.join(ROOT, "_includes", name), + File.join(includes, name) + ) + end + + File.write( + File.join(source, "index.html"), + "---\n---\n{% include api_lua_v2.html ref=site.data.ref %}\n" + ) + File.write( + File.join(data, "ref.json"), + JSON.pretty_generate(reference_document) + ) + + site = Jekyll::Site.new(Jekyll.configuration( + "source" => source, + "destination" => destination, + "cache_dir" => File.join(directory, "cache"), + "quiet" => true + )) + site.process + + rendered = File.read(File.join(destination, "index.html")) + assert_includes( + rendered, + 'render.render_target_params = '
+ )
+ assert_includes rendered, "Use code formatting."
+ end
+ end
+
+ private
+
+ def reference_document
+ {
+ "info" => {
+ "brief" => "Render API",
+ "description_html" => "Render documentation."
+ },
+ "elements" => [
+ {
+ "type" => "TYPEDEF",
+ "name" => "render.render_target_params",
+ "brief" => "Render-target parameters.",
+ "target_type_html" => (
+ "{ sample_count?:integer, " \
+ "[graphics.BUFFER_TYPE]:render.render_target_buffer_params }"
+ ),
+ "description" => "Target configuration.",
+ "examples" => []
+ },
+ {
+ "type" => "STRUCT",
+ "name" => "render.render_target_buffer_params",
+ "brief" => "Render-target buffer parameters.",
+ "description" => "Buffer configuration.",
+ "examples" => [],
+ "members" => [
+ {
+ "display_name" => "format",
+ "is_optional" => false,
+ "type_html" => "graphics.TEXTURE_FORMAT",
+ "doc" => "Use code formatting."
+ }
+ ]
+ }
+ ]
+ }
+ end
+end
diff --git a/tests/test_refdoc.py b/tests/test_refdoc.py
index 40d8a4fbf..2e789f194 100644
--- a/tests/test_refdoc.py
+++ b/tests/test_refdoc.py
@@ -28,14 +28,10 @@ def test_prepares_v2_lua_types_and_enum_members(self):
"type": "ENUM",
"name": "go.EASING",
"parameters": [],
- "members": [],
- },
- {
- "type": "CONSTANT",
- "name": "go.EASING_LINEAR",
- "brief": "linear easing",
- "description": "",
- "parameters": [],
+ "members": [{
+ "name": "go.EASING_LINEAR",
+ "doc": "Use linear easing.",
+ }],
},
{
"type": "CONSTANT",
@@ -50,24 +46,81 @@ def test_prepares_v2_lua_types_and_enum_members(self):
{
"type": "STRUCT",
"name": "on_input.action",
- "members": [{"name": "pressed?", "type": "boolean"}],
+ "members": [{
+ "name": "pressed?",
+ "type": "boolean",
+ "doc": "Use true when pressed.",
+ }],
},
],
}
prepared = refdoc.prepare_lua_v2(copy.deepcopy(api))
- enum, enum_constant, standalone, alias, record = prepared["elements"]
+ enum, standalone, alias, record = prepared["elements"]
self.assertEqual("integer", enum["value_type"])
self.assertEqual(
- [{"name": "go.EASING_LINEAR", "doc": "linear easing"}],
+ [{
+ "name": "go.EASING_LINEAR",
+ "doc": "Use linear easing.",
+ }],
enum["members"])
- self.assertTrue(enum_constant["is_enum_member"])
- self.assertEqual("go.EASING", enum_constant["value_type"])
self.assertFalse(standalone["is_enum_member"])
self.assertEqual("string | url", alias["target_type"])
self.assertEqual("pressed", record["members"][0]["display_name"])
self.assertTrue(record["members"][0]["is_optional"])
+ self.assertEqual(
+ "Use true when pressed.",
+ record["members"][0]["doc"])
+
+ def test_v2_enum_requires_explicit_members(self):
+ api = {
+ "format_version": 2,
+ "info": {"api_language": "Lua"},
+ "elements": [
+ {
+ "type": "ENUM",
+ "name": "go.EASING",
+ "parameters": [],
+ "members": [],
+ },
+ {
+ "type": "CONSTANT",
+ "name": "go.EASING_LINEAR",
+ "parameters": [],
+ },
+ ],
+ }
+
+ with self.assertRaisesRegex(
+ ValueError,
+ r"enum go\.EASING must declare at least one explicit member"):
+ refdoc.prepare_lua_v2(api)
+
+ def test_v2_enum_rejects_duplicate_standalone_member(self):
+ api = {
+ "format_version": 2,
+ "info": {"api_language": "Lua"},
+ "elements": [
+ {
+ "type": "ENUM",
+ "name": "go.EASING",
+ "parameters": [],
+ "members": [{"name": "go.EASING_LINEAR", "doc": ""}],
+ },
+ {
+ "type": "CONSTANT",
+ "name": "go.EASING_LINEAR",
+ "parameters": [],
+ },
+ ],
+ }
+
+ with self.assertRaisesRegex(
+ ValueError,
+ r"enum go\.EASING member go\.EASING_LINEAR is also declared "
+ r"as a standalone constant"):
+ refdoc.prepare_lua_v2(api)
def test_links_documented_and_builtin_types(self):
namespaces = {
@@ -75,7 +128,14 @@ def test_links_documented_and_builtin_types(self):
"format_version": 2,
"info": {"api_language": "Lua"},
"elements": [
- {"type": "ENUM", "name": "go.PLAYBACK"},
+ {
+ "type": "ENUM",
+ "name": "go.PLAYBACK",
+ "members": [{
+ "name": "go.PLAYBACK_ONCE_FORWARD",
+ "doc": "Play once.",
+ }],
+ },
{
"type": "FUNCTION",
"name": "go.animate",