Fix invalid link in edoc notes and Markdown

This PR fixes the below warnings during doc generation: warning: documentation references "e:system/documentation.md" but it is invalid └─ notes.md: (file) This also includes some Markdown and indentation issues as well.
erlang · Jun 15, 2024 · 0bb08fc · 0bb08fc
1 parent 56ca964
commit 0bb08fc
Show file tree

Hide file tree

Showing 3 changed files with 19 additions and 20 deletions.
diff --git a/lib/edoc/doc/notes.md b/lib/edoc/doc/notes.md
@@ -46,7 +46,7 @@ This document describes the changes made to the EDoc application.
 
   Own Id: OTP-18955 Aux Id: [PR-8026]
 
-- Added module `m:edoc_doclet_markdown` that can be used to convert EDoc style documentation to [Markdown documentation attributes](`e:system/documentation.md`).
+- Added module `m:edoc_doclet_markdown` that can be used to convert EDoc style documentation to [Markdown documentation attributes](`e:system:documentation.md`).
 
   Own Id: OTP-19052 Aux Id: [PR-8308]
 

diff --git a/lib/edoc/src/edoc_doclet_markdown.erl b/lib/edoc/src/edoc_doclet_markdown.erl
@@ -18,7 +18,7 @@
 %% %CopyrightEnd%
 %%
 
-%% @doc Doclet converting an edoc application to use EEP-59 and markdown.
+%% @doc Doclet converting an edoc application to use <a href="https://www.erlang.org/eeps/eep-0059">EEP-59</a> and Markdown.
 %%
 %% This doclet has to be used together with {@link edoc_layout_chunks}.
 %%
@@ -29,8 +29,8 @@
 %%      {layout, edoc_layout_chunks}]).
 %% '''
 %%
-%% It will convert the overview to markdown and any module documentation to use
-%% `-doc' attributes and markdown. Any XHTML tags in the edoc documentation that are
+%% It will convert the overview to Markdown and any module documentation to use
+%% `-doc' attributes and Markdown. Any XHTML tags in the edoc documentation that are
 %% not part of the tags supported by <a href="doc_storage.html#erlang-documentation-format">
 %% Erlang Documentation Format</a> will be added as HTML tags in the Markdown.
 %%
@@ -183,7 +183,7 @@ source({Module, Name, Path}, App, Env, OkSet, ErrorFlag, Options0) ->
                       string:split(Bin, "\n", all);
                   F -> F
               end),
-        
+
         NewFilesWithModuleDoc =
             NewFiles#{ ModuleAttrFilename =>
                            BeforeModule ++

diff --git a/system/doc/reference_manual/documentation.md b/system/doc/reference_manual/documentation.md
@@ -102,7 +102,7 @@ The `-moduledoc` and `-doc` can also be placed in external files. To do so use
 `-doc {file, "path/to/doc.md"}` to point to the documentation. The path used is
 relative to the file where the `-doc` attribute is located. For example:
 
-```text
+```markdown
 %% doc/add.md
 Adds two numbers.
 ```
@@ -260,8 +260,7 @@ specification. For example:
 -callback increment(In :: number()) -> Out.
 %% signature will be `increment(In)`
 
--callback increment(In) -> Out when
-   In :: number().
+-callback increment(In) -> Out when In :: number().
 %% signature will be `increment(In)`
 ```
 
@@ -322,7 +321,7 @@ The link can also other entities:
 Example:
 
 ```erlang
-  -doc "See `arith:sub/2` for more details".
+-doc "See `arith:sub/2` for more details".
 ```
 
 - `modules` - Write the module with a `m` prefix. Use anchors to jump to a
@@ -331,8 +330,8 @@ Example:
 Example:
 
 ```erlang
-  -doc "See `m:arith` for more details".
-  -doc "See `m:arith#anchor` for more details".
+-doc "See `m:arith` for more details".
+-doc "See `m:arith#anchor` for more details".
 ```
 
 - `types` - Use the same syntax as for local/remote function but add a `t`
@@ -341,8 +340,8 @@ Example:
 Example:
 
 ```erlang
-  -doc "See `t:number/0` for more details".
-  -doc "See `t:arith:number/0` for more details".
+-doc "See `t:number/0` for more details".
+-doc "See `t:arith:number/0` for more details".
 ```
 
 - `callbacks` - Use the same syntax as for local/remote function but add a `c`
@@ -351,8 +350,8 @@ Example:
 Example:
 
 ```erlang
-  -doc "See `c:increment/0` for more details".
-  -doc "See `c:arith:increment/0` for more details".
+-doc "See `c:increment/0` for more details".
+-doc "See `c:arith:increment/0` for more details".
 ```
 
 - `extra pages` - For extra pages in the current application use a normal link,
@@ -363,8 +362,8 @@ Example:
 Example:
 
 ```erlang
-  -doc "See `e:stdlib:unicode_usage` for more details".
-  -doc "See `e:stdlib:unicode_usage#notes-about-raw-filenames` for more details".
+-doc "See `e:stdlib:unicode_usage` for more details".
+-doc "See `e:stdlib:unicode_usage#notes-about-raw-filenames` for more details".
 ```
 
 ## What is visible versus hidden?
@@ -450,9 +449,9 @@ documentation add the following to your `rebar3.config`.
 {plugins, [rebar3_ex_doc]}.
 
 {ex_doc, [
- {extras, ["README.md"]},
- {main, "README.md"},
- {source_url, "https://github.com/namespace/your_app"}
+  {extras, ["README.md"]},
+  {main, "README.md"},
+  {source_url, "https://github.com/namespace/your_app"}
 ]}.
 ```