From 7cd580876626448df246c86a50b510ed9f87befb Mon Sep 17 00:00:00 2001 From: Badlop Date: Fri, 22 Mar 2024 12:50:47 +0100 Subject: [PATCH] Mark toplevel options, commands and modules that changed in latest version --- src/ejabberd_commands_doc.erl | 32 +++++++++++++++++++++++--------- src/ejabberd_doc.erl | 33 ++++++++++++++++++++++++--------- 2 files changed, 47 insertions(+), 18 deletions(-) diff --git a/src/ejabberd_commands_doc.erl b/src/ejabberd_commands_doc.erl index 2b26b4800..7b0b46246 100644 --- a/src/ejabberd_commands_doc.erl +++ b/src/ejabberd_commands_doc.erl @@ -415,7 +415,7 @@ gen_doc(#ejabberd_commands{name=Name, tags=Tags, desc=Desc, longdesc=LongDesc, true -> {NoteEl, []} end, - [?TAG(h1, atom_to_list(Name)), + [?TAG(h1, make_command_name(Name, Note)), NotePre, ?TAG(p, ?RAW(Desc)), case LongDesc of @@ -435,6 +435,19 @@ gen_doc(#ejabberd_commands{name=Name, tags=Tags, desc=Desc, longdesc=LongDesc, [Name, Ex]))) end. +get_version_mark("") -> + ""; +get_version_mark(Note) -> + [XX, YY | _] = string:tokens(binary_to_list(ejabberd_option:version()), "."), + XXYY = string:join([XX, YY], "."), + case string:find(Note, XXYY) of + nomatch -> ""; + _ -> " 🟤" + end. + +make_command_name(Name, Note) -> + atom_to_list(Name) ++ get_version_mark(Note). + find_commands_definitions() -> lists:flatmap( fun(Mod) -> @@ -492,21 +505,22 @@ generate_md_output(File, RegExp, Languages, Cmds) -> end, Cmds2), Cmds4 = [maybe_add_policy_arguments(Cmd) || Cmd <- Cmds3], Langs = binary:split(Languages, <<",">>, [global]), - Version = ejabberd_config:version(), - Header = <<"# API Reference\n\n" - "This section describes API of ejabberd ", Version/binary, ".\n\n">>, + Version = binary_to_list(ejabberd_config:version()), + Header = ["# API Reference\n\n" + "This section describes API commands of ejabberd ", Version, ". " + "The commands that changed in this version are marked with 🟤.\n\n"], Out = lists:map(fun(C) -> gen_doc(C, false, Langs) end, Cmds4), - {ok, Fh} = file:open(File, [write]), + {ok, Fh} = file:open(File, [write, {encoding, utf8}]), io:format(Fh, "~ts~ts", [Header, Out]), file:close(Fh), ok. generate_tags_md(File) -> - Version = ejabberd_config:version(), - Header = <<"# API Tags\n\n" - "This section enumerates the API tags of ejabberd ", Version/binary, ".\n\n">>, + Version = binary_to_list(ejabberd_config:version()), + Header = ["# API Tags\n\n" + "This section enumerates the API tags of ejabberd ", Version, ". \n\n"], Tags = make_tags(false), - {ok, Fh} = file:open(File, [write]), + {ok, Fh} = file:open(File, [write, {encoding, utf8}]), io:format(Fh, "~ts~ts", [Header, Tags]), file:close(Fh), ok. diff --git a/src/ejabberd_doc.erl b/src/ejabberd_doc.erl index 389be0f81..28a6e1a5c 100644 --- a/src/ejabberd_doc.erl +++ b/src/ejabberd_doc.erl @@ -45,7 +45,8 @@ man(Lang) -> #{desc := Descr} = Map -> DocOpts = maps:get(opts, Map, []), Example = maps:get(example, Map, []), - {[{M, Descr, DocOpts, #{example => Example}}|Mods], SubMods}; + Note = maps:get(note, Map, []), + {[{M, Descr, DocOpts, #{example => Example, note => Note}}|Mods], SubMods}; #{opts := DocOpts} -> {ParentMod, Backend} = strip_backend_suffix(M), {Mods, dict:append(ParentMod, {M, Backend, DocOpts}, SubMods)}; @@ -72,11 +73,12 @@ man(Lang) -> catch _:undef -> [] end end, ejabberd_config:callback_modules(all)), - Version = ejabberd_config:version(), + Version = binary_to_list(ejabberd_config:version()), Options = ["TOP LEVEL OPTIONS", "-----------------", - tr(Lang, <<"This section describes top level options of ejabberd ", Version/binary, ".">>), + "This section describes top level options of ejabberd " ++ Version ++ ".", + "The options that changed in this version are marked with 🟤.", io_lib:nl()] ++ lists:flatmap( fun(Opt) -> @@ -96,13 +98,15 @@ man(Lang) -> "MODULES", "-------", "[[modules]]", - tr(Lang, <<"This section describes modules options of ejabberd ", Version/binary, ".">>), + "This section describes modules options of ejabberd " ++ Version ++ ".", + "The modules that changed in this version are marked with 🟤.", io_lib:nl()] ++ lists:flatmap( fun({M, Descr, DocOpts, Backends, Example}) -> ModName = atom_to_list(M), + VersionMark = get_version_mark(Example), [io_lib:nl(), - ModName, + lists:flatten([ModName, VersionMark]), lists:duplicate(length(atom_to_list(M)), $~), "[[" ++ ModName ++ "]]", io_lib:nl()] ++ @@ -115,7 +119,7 @@ man(Lang) -> "LISTENERS", "-------", "[[listeners]]", - tr(Lang, <<"This section describes listeners options of ejabberd ", Version/binary, ".">>), + "This section describes listeners options of ejabberd " ++ Version ++ ".", io_lib:nl(), "TODO"], AsciiData = @@ -163,13 +167,24 @@ opt_to_man(Lang, {Option, Options, Children}, Level) -> lists:keysort(1, Children))]) ++ [io_lib:nl()|format_example(Level, Lang, Options)]. -format_option(Lang, Option, #{value := Val}) -> - "*" ++ atom_to_list(Option) ++ "*: 'pass:[" ++ +get_version_mark(#{note := Note}) -> + [XX, YY | _] = string:tokens(binary_to_list(ejabberd_option:version()), "."), + XXYY = string:join([XX, YY], "."), + case string:find(Note, XXYY) of + nomatch -> ""; + _ -> " 🟤" + end; +get_version_mark(_) -> + "". + +format_option(Lang, Option, #{value := Val} = Options) -> + VersionMark = get_version_mark(Options), + "*" ++ atom_to_list(Option) ++ VersionMark ++ "*: 'pass:[" ++ tr(Lang, Val) ++ "]'::"; format_option(_Lang, Option, #{}) -> "*" ++ atom_to_list(Option) ++ "*::". -format_versions(Lang, #{note := Note}) -> +format_versions(_Lang, #{note := Note}) -> ["_Note_ about this option: " ++ Note ++ ". "]; format_versions(_, _) -> [].