Fix EDoc documentation syntax errors

benoitc · benoitc · commit 21ce626a5aaf · 2026-02-18T10:40:57.000+01:00
- Remove deprecated @type tags (use -type attributes instead) - Replace Markdown backticks with plain text - Convert Markdown lists to EDoc HTML lists - Simplify code examples in module docs
diff --git a/src/py_asgi.erl b/src/py_asgi.erl
@@ -17,53 +17,35 @@
 %%% This module provides high-performance ASGI request handling by using
 %%% optimized C-level marshalling between Erlang and Python:
 %%%
-%%% - **Interned keys**: ASGI scope keys are pre-interned Python strings,
-%%%   eliminating per-request string allocation and hashing overhead.
-%%%
-%%% - **Cached constants**: Common values like `"http"`, `"1.1"`, `"GET"`,
-%%%   etc. are reused across requests.
-%%%
-%%% - **Response pooling**: Pre-allocated response structures reduce
-%%%   memory allocation during request processing.
-%%%
-%%% - **Direct NIF path**: Bypasses generic py:call() for ASGI-specific
-%%%   optimizations.
+%%% <ul>
+%%% <li>Interned keys: ASGI scope keys are pre-interned Python strings,
+%%%   eliminating per-request string allocation and hashing overhead.</li>
+%%% <li>Cached constants: Common values like "http", "1.1", "GET",
+%%%   etc. are reused across requests.</li>
+%%% <li>Response pooling: Pre-allocated response structures reduce
+%%%   memory allocation during request processing.</li>
+%%% <li>Direct NIF path: Bypasses generic py:call() for ASGI-specific
+%%%   optimizations.</li>
+%%% </ul>
 %%%
 %%% == Performance ==
 %%%
-%%% Compared to generic py:call()-based ASGI handling:
-%%%
-%%% | Optimization | Improvement |
-%%% |--------------|-------------|
-%%% | Interned keys | +15-20% throughput |
-%%% | Response pooling | +20-25% throughput |
-%%% | Direct NIF | +25-30% throughput |
-%%% | **Total** | ~60-80% improvement |
+%%% Compared to generic py:call()-based ASGI handling, this module
+%%% provides approximately 60-80% throughput improvement through
+%%% interned keys (+15-20%), response pooling (+20-25%), and
+%%% direct NIF path (+25-30%).
 %%%
 %%% == Usage ==
 %%%
-%%% ```erlang
-%%% %% Build ASGI scope from Cowboy request
+%%% ```
 %%% Scope = #{
 %%%     type => <<"http">>,
-%%%     http_version => <<"1.1">>,
 %%%     method => <<"GET">>,
-%%%     scheme => <<"http">>,
-%%%     path => <<"/api/users">>,
-%%%     query_string => <<"id=123">>,
-%%%     headers => [[<<"host">>, <<"localhost:8080">>]],
-%%%     server => {<<"localhost">>, 8080},
-%%%     client => {<<"127.0.0.1">>, 54321}
+%%%     path => <<"/api/users">>
 %%% },
-%%%
-%%% %% Execute ASGI application
 %%% case py_asgi:run(<<"myapp">>, <<"application">>, Scope, Body) of
-%%%     {ok, {Status, Headers, ResponseBody}} ->
-%%%         %% Send response
-%%%         cowboy_req:reply(Status, Headers, ResponseBody, Req);
-%%%     {error, Reason} ->
-%%%         %% Handle error
-%%%         cowboy_req:reply(500, #{}, <<"Internal Server Error">>, Req)
+%%%     {ok, {Status, Headers, ResponseBody}} -> ok;
+%%%     {error, Reason} -> error
 %%% end.
 %%% '''
 %%%
@@ -82,21 +64,6 @@
     scope_opts/0
 ]).
 
-%% @type scope() = #{
-%%   type := binary(),
-%%   asgi => #{version => binary(), spec_version => binary()},
-%%   http_version => binary(),
-%%   method => binary(),
-%%   scheme => binary(),
-%%   path := binary(),
-%%   raw_path => binary(),
-%%   query_string => binary(),
-%%   root_path => binary(),
-%%   headers => [[binary()]],
-%%   server => {binary(), integer()},
-%%   client => {binary(), integer()},
-%%   state => map()
-%% }.
 %% ASGI scope dictionary.
 -type scope() :: #{
     type := binary(),
@@ -115,10 +82,6 @@
     extensions => map()
 }.
 
-%% @type scope_opts() = #{
-%%   state => map(),
-%%   extensions => map()
-%% }.
 %% Options for scope building.
 -type scope_opts() :: #{
     state => map(),
@@ -143,7 +106,9 @@ run(Module, Callable, Scope, Body) ->
 %% @doc Execute an ASGI application with options.
 %%
 %% Additional options:
-%% - `timeout` - Request timeout in milliseconds (default: 30000)
+%% <ul>
+%% <li>runner - Custom Python runner module name</li>
+%% </ul>
 %%
 %% @param Module Python module containing the ASGI application
 %% @param Callable Name of the ASGI callable
diff --git a/src/py_nif.erl b/src/py_nif.erl
@@ -756,21 +756,22 @@ asgi_build_scope(_ScopeMap) ->
 %% @doc Execute an ASGI application with optimized marshalling.
 %%
 %% This is a direct NIF that bypasses the generic py:call() path:
-%% - Builds scope dict using interned keys
-%% - Uses response pooling
-%% - Runs the ASGI app coroutine synchronously
+%% <ul>
+%% <li>Builds scope dict using interned keys</li>
+%% <li>Uses response pooling</li>
+%% <li>Runs the ASGI app coroutine synchronously</li>
+%% </ul>
 %%
-%% Requires the `hornbeam_asgi_runner` Python module to be available,
-%% which provides the `_run_asgi_sync` function that handles the
+%% Requires the hornbeam_asgi_runner Python module to be available,
+%% which provides the _run_asgi_sync function that handles the
 %% ASGI receive/send protocol.
 %%
-%% @param Runner Python runner module name (e.g., <<"hornbeam_asgi_runner">>)
-%% @param Module Application module name (e.g., <<"myapp.asgi">>)
-%% @param Callable ASGI callable name (e.g., <<"application">>)
+%% @param Runner Python runner module name
+%% @param Module Application module name
+%% @param Callable ASGI callable name
 %% @param ScopeMap Erlang map containing ASGI scope (see asgi_build_scope/1)
 %% @param Body Request body as binary
-%% @returns {ok, {Status, Headers, Body}} on success,
-%%          or {error, Reason}
+%% @returns {ok, {Status, Headers, Body}} on success, or {error, Reason}
 -spec asgi_run(binary(), binary(), binary(), map(), binary()) ->
     {ok, {integer(), [{binary(), binary()}], binary()}} | {error, term()}.
 asgi_run(_Runner, _Module, _Callable, _ScopeMap, _Body) ->
@@ -783,20 +784,21 @@ asgi_run(_Runner, _Module, _Callable, _ScopeMap, _Body) ->
 %% @doc Execute a WSGI application with optimized marshalling.
 %%
 %% This is a direct NIF that bypasses the generic py:call() path:
-%% - Builds environ dict using interned keys
-%% - Uses cached constant values
-%% - Runs the WSGI app synchronously
+%% <ul>
+%% <li>Builds environ dict using interned keys</li>
+%% <li>Uses cached constant values</li>
+%% <li>Runs the WSGI app synchronously</li>
+%% </ul>
 %%
-%% Requires the `hornbeam_wsgi_runner` Python module to be available,
-%% which provides the `_run_wsgi_sync` function that handles the
+%% Requires the hornbeam_wsgi_runner Python module to be available,
+%% which provides the _run_wsgi_sync function that handles the
 %% WSGI start_response protocol.
 %%
-%% @param Runner Python runner module name (e.g., <<"hornbeam_wsgi_runner">>)
-%% @param Module Application module name (e.g., <<"myapp.wsgi">>)
-%% @param Callable WSGI callable name (e.g., <<"application">>)
+%% @param Runner Python runner module name
+%% @param Module Application module name
+%% @param Callable WSGI callable name
 %% @param EnvironMap Erlang map containing WSGI environ
-%% @returns {ok, {Status, Headers, Body}} on success,
-%%          or {error, Reason}
+%% @returns {ok, {Status, Headers, Body}} on success, or {error, Reason}
 -spec wsgi_run(binary(), binary(), binary(), map()) ->
     {ok, {binary(), [{binary(), binary()}], binary()}} | {error, term()}.
 wsgi_run(_Runner, _Module, _Callable, _EnvironMap) ->
diff --git a/src/py_wsgi.erl b/src/py_wsgi.erl
@@ -17,49 +17,31 @@
 %%% This module provides high-performance WSGI request handling by using
 %%% optimized C-level marshalling between Erlang and Python:
 %%%
-%%% - **Interned keys**: WSGI environ keys are pre-interned Python strings,
-%%%   eliminating per-request string allocation and hashing overhead.
-%%%
-%%% - **Cached constants**: Common values like `"GET"`, `"HTTP/1.1"`,
-%%%   etc. are reused across requests.
-%%%
-%%% - **Direct NIF path**: Bypasses generic py:call() for WSGI-specific
-%%%   optimizations.
+%%% <ul>
+%%% <li>Interned keys: WSGI environ keys are pre-interned Python strings,
+%%%   eliminating per-request string allocation and hashing overhead.</li>
+%%% <li>Cached constants: Common values like "GET", "HTTP/1.1",
+%%%   etc. are reused across requests.</li>
+%%% <li>Direct NIF path: Bypasses generic py:call() for WSGI-specific
+%%%   optimizations.</li>
+%%% </ul>
 %%%
 %%% == Performance ==
 %%%
-%%% Compared to generic py:call()-based WSGI handling:
-%%%
-%%% | Optimization | Improvement |
-%%% |--------------|-------------|
-%%% | Interned keys | +15-20% throughput |
-%%% | Direct NIF | +25-30% throughput |
-%%% | **Total** | ~60-80% improvement |
+%%% Compared to generic py:call()-based WSGI handling, this module
+%%% provides approximately 60-80% throughput improvement through
+%%% interned keys (+15-20%) and direct NIF path (+25-30%).
 %%%
 %%% == Usage ==
 %%%
-%%% ```erlang
-%%% %% Build WSGI environ from Cowboy request
+%%% ```
 %%% Environ = #{
 %%%     <<"REQUEST_METHOD">> => <<"GET">>,
-%%%     <<"SCRIPT_NAME">> => <<>>,
-%%%     <<"PATH_INFO">> => <<"/api/users">>,
-%%%     <<"QUERY_STRING">> => <<"id=123">>,
-%%%     <<"SERVER_NAME">> => <<"localhost">>,
-%%%     <<"SERVER_PORT">> => <<"8080">>,
-%%%     <<"SERVER_PROTOCOL">> => <<"HTTP/1.1">>,
-%%%     <<"wsgi.url_scheme">> => <<"http">>,
-%%%     <<"wsgi.input">> => Body
+%%%     <<"PATH_INFO">> => <<"/api/users">>
 %%% },
-%%%
-%%% %% Execute WSGI application
 %%% case py_wsgi:run(<<"myapp">>, <<"application">>, Environ) of
-%%%     {ok, {Status, Headers, ResponseBody}} ->
-%%%         %% Send response
-%%%         StatusCode = parse_status(Status),
-%%%         cowboy_req:reply(StatusCode, Headers, ResponseBody, Req);
-%%%     {error, Reason} ->
-%%%         cowboy_req:reply(500, #{}, <<"Internal Server Error">>, Req)
+%%%     {ok, {Status, Headers, ResponseBody}} -> ok;
+%%%     {error, Reason} -> error
 %%% end.
 %%% '''
 %%%
@@ -75,7 +57,6 @@
     environ/0
 ]).
 
-%% @type environ() = #{binary() => binary() | integer() | atom()}.
 %% WSGI environ dictionary.
 -type environ() :: #{
     binary() => binary() | integer() | atom()
@@ -98,7 +79,9 @@ run(Module, Callable, Environ) ->
 %% @doc Execute a WSGI application with options.
 %%
 %% Additional options:
-%% - `runner` - Python runner module name (default: <<"hornbeam_wsgi_runner">>)
+%% <ul>
+%% <li>runner - Python runner module name (default: hornbeam_wsgi_runner)</li>
+%% </ul>
 %%
 %% @param Module Python module containing the WSGI application
 %% @param Callable Name of the WSGI callable
