feat: add ?IMPORTANCE_NO_DOC importance

For fields that are meant to be returned in APIs, but are not to have their documentation generated.
emqx · Jul 19, 2024 · 0952503 · 0952503
1 parent fc0451c
commit 0952503
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 1 deletion.
diff --git a/include/hoconsc.hrl b/include/hoconsc.hrl
@@ -26,6 +26,8 @@
 -define(IMPORTANCE_MEDIUM, medium).
 %% not important, usually only for advanced users
 -define(IMPORTANCE_LOW, low).
+%% hidden from documentation, but still returned by HTTP APIs and raw config
+-define(IMPORTANCE_NO_DOC, no_doc).
 %% hidden for normal users, only experts should need to care
 -define(IMPORTANCE_HIDDEN, hidden).
 

diff --git a/src/hocon_schema.erl b/src/hocon_schema.erl
@@ -88,7 +88,11 @@
 -type desc() :: iodata() | {desc, module(), desc_id()}.
 -type union_selector() :: fun((all_union_members | {value, _}) -> type() | [type()]).
 -type union_members() :: [type()] | union_selector().
--type importance() :: ?IMPORTANCE_HIGH | ?IMPORTANCE_MEDIUM | ?IMPORTANCE_LOW | ?IMPORTANCE_HIDDEN.
+-type importance() :: ?IMPORTANCE_HIGH
+                    | ?IMPORTANCE_MEDIUM
+                    | ?IMPORTANCE_LOW
+                    | ?IMPORTANCE_NO_DOC
+                    | ?IMPORTANCE_HIDDEN.
 %% primitive (or complex, but terminal) type
 -type type() ::
     typerefl:type()
@@ -572,6 +576,7 @@ is_hidden(Schema, Opts) ->
     importance_num(DefinedImprotance) < importance_num(NeededImportance).
 
 importance_num(?IMPORTANCE_HIDDEN) -> 0;
+importance_num(?IMPORTANCE_NO_DOC) -> 6;
 importance_num(?IMPORTANCE_LOW) -> 7;
 importance_num(?IMPORTANCE_MEDIUM) -> 8;
 importance_num(?IMPORTANCE_HIGH) -> 9.

diff --git a/test/hocon_tconf_tests.erl b/test/hocon_tconf_tests.erl
@@ -1638,6 +1638,13 @@ no_default_value_fill_for_hidden_fields_test() ->
                         hoconsc:mk(
                             hoconsc:array(integer()),
                             #{default => [$d]}
+                        )},
+                    {"e",
+                        hoconsc:mk(
+                            hoconsc:array(integer()), #{
+                               default => [$e],
+                                                        importance => ?IMPORTANCE_NO_DOC
+                             }
                         )}
                 ]
         }
@@ -1650,6 +1657,9 @@ no_default_value_fill_for_hidden_fields_test() ->
     C3 = #{<<"a">> => #{<<"c">> => 2}},
     C4 = #{<<"a">> => #{<<"c">> => 2, <<"d">> => [$d]}},
     ?assertEqual(C4, hocon_tconf:make_serializable(Sc, C3, #{})),
+    C5 = #{<<"a">> => #{<<"e">> => [3]}},
+    C6 = #{<<"a">> => #{<<"d">> => [$d], <<"e">> => [3]}},
+    ?assertEqual(C6, hocon_tconf:make_serializable(Sc, C5, #{})),
     ok.
 
 root_array_test_() ->