Documentation updates #1021

UncleGrumpy · 2024-01-31T02:46:14Z

Updates and corrections to the documentation, as well as some cleanup of the documentation build system itself.

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

src/libAtomVM/opcodesswitch.h

CONTRIBUTING.md

bettio · 2024-01-31T23:10:48Z

CONTRIBUTING.md


-> Note: You should include a short `/* comment */` trailing the `#ifndef` entry mentioning the file where the function is actually documented.
+```{admonition} Note:


Is {admonition} something parsed from GitHub?

I just discovered that this format doesn't work well, so I am already in the process of changing all of the {admonition}'s to a more portable style.

bettio · 2024-01-31T23:16:27Z

README.Md

@@ -26,9 +26,9 @@ might be supported in a near future.

 Getting Started
 ===============
-There is much more information, including a more complete (["Getting Started Guide"](https://www.atomvm.net/doc/master/getting-started-guide.html)), ([extensive documentation](https://www.atomvm.net/doc/master/build-instructions.html)), ([examples](https://www.atomvm.net/sample-code)), detailed ([build instructions](https://www.atomvm.net/doc/master/build-instructions.html)) and ([contact information](https://www.atomvm.net/contact)) available on the [AtomVM](https://atomvm.net) project website.
+There is much more information, including a more complete ["Getting Started Guide"](https://www.atomvm.net/doc/master/getting-started-guide.html), [extensive documentation](https://www.atomvm.net/doc/master/build-instructions.html), [examples](https://www.atomvm.net/sample-code), detailed [build instructions](https://www.atomvm.net/doc/master/build-instructions.html) and [contact information](https://www.atomvm.net/contact) available on the [AtomVM](https://atomvm.net) project website.


Since we are changing this block of text, would you mind trying to fit as much as possible into 100 character columns?
Let's change it while changing the text.

Update links for build instructions on various platforms. Fixes several links in the Getting Started section that were places within parentheses, which led to undesireable formatting in the rendered text. Signed-off-by: Winford <winford@object.stream>

Various typo corrections, add missing parmaters, and other format fixes for the API documentation generated from library source code files. Signed-off-by: Winford <winford@object.stream>

The fix in uwiger/edown#30 has been merged upsteam, so we should now return to using the upstream tool available from hex. Removes unnecessary `ex_doc` plugin. Signed-off-by: Winford <winford@object.stream>

fadushin

I was able to build locally; looks great!

src/libAtomVM/opcodesswitch.h

bettio · 2024-02-05T23:14:28Z

libs/estdlib/src/erlang.erl

-    (Pid :: pid(), memory) -> {memory, non_neg_integer()};
-    (Pid :: pid(), links) -> {links, [pid()]}.
+-spec process_info(Pid :: pid(), Key :: atom()) ->
+    {LookupKey :: atom(), Value :: non_neg_integer()} | {links, [LinkPid :: pid()]}.


are we sure about this change?

You can see how the current spec gets published here:
https://www.atomvm.net/doc/master/apidocs/erlang/estdlib/erlang.html#process-info-2

I believe the updated spec is correct, and the formatting looks much better, here in a screenshot of how the updated spec changes the output:

I don't mind reverting this change, but I think the more concise version looks better, while still conveying all of the correct information.

This change doesn't look just cosmetic to me, we are changing to a less specific typespec.
CC @fadushin or @pguyot

Just as a point of reference here is the OTP spec:

process_info(Pid, Item) -> InfoTuple | [] | undefined
process_info(Pid, ItemList) -> InfoTupleList | [] | undefined

It might be better if I change this to closer to the OTP definition, and add a typespec for InfoTuple.

bettio · 2024-02-05T23:23:01Z

libs/exavmlib/mix.exs.in

@@ -0,0 +1,75 @@
+#


I'm not really sure why this is .in file, can't we make a real mix.exs file instead of templating it?

This was included by mistake. It was from a work-in-progress to include the elixir documentation in our published API docs, which is not ready to PR yet. It has been removed.

bettio · 2024-02-06T19:28:08Z

libs/eavmlib/src/emscripten.erl

+%% @param TargetOrHandle Target or handle
+%% @returns ok or `{error, Reason}'
+%% @end
+-spec unregister_touchcancel_callback(TargetOrHandle :: html5_target() | listener_handle()) ->


is changing spec from unregister_touchcancel_callback(html5_target() | listener_handle()) to unregister_touchcancel_callback(TargetOrHandle :: html5_target() | listener_handle()) a requirement?

Not including the argument name in in the spec (i.e. only the type) prevents the argument from being displayed in the documentation.

bettio · 2024-02-06T19:31:10Z

doc/src/atomvm-internals.md

- The `emscripten:promise_resolve/1,2` and `emscripten:promise_reject/1,2` nifs dispatch a message in the browser's main thread.
- The dispatched function retrieves the promise from its index, resolves or rejects it, with the value passed to `emscripten:promise_resolve/2` or `emscripten:promise_reject/2` and destroys it.
+1. A promise is created (in the browser's main thread) in a map to prevent Javascript garbage collection (this is done by Emscripten's promise glue code).
+1. An Erlang resource is created to encapsulate the promise so it is properly destroyed when garbage collected


I'm not sure I'm understanding this kind of change.

I changed that from and unordered list to and ordered one, since this is a specific sequence of events. The rendered list will be numbered 1, 2, 3, etc automatically.

bettio · 2024-02-06T19:37:45Z

I feel like this is quite hard to deal with this kind of PR, it mixes together changes to how we build documentation (CMakeLists.txt), to configuration, typos and typespecs.
Hence straightforward typo correction that should be merged with a no brainer review, clutters quite a lot things that should be reviewed carefully.

UncleGrumpy · 2024-02-06T20:01:56Z

I did make sure that any changes that to actual code is in a separate commit. But I can pull out the build changes from the documentation updates into a separate commit.

Various corrections, formatting fixes, updates, and visual enhancements to the generated documentation. Signed-off-by: Winford <winford@object.stream>

Adds pdf template and stylesheet to fix the way links to sections are rendered by the spinx `rinoh` plugin, using the given section name for the link rather than replacing them with the section heading number. Reduces the verbosity of Doxgen, and no longer produce the duplicate doxygen html content. Removes unnecessary Sphinx plugins, adds html metadata (for better SEO), and reorganizes `conf.py.in` so that settings are less scattered and grouped into labeled sections. Several configuration options have been added to help solve many of the build warings, and several kinds of unhelpful, or false-positive warnings from Sphinx have been supressed. Changes to CMakeLists.txt remove several unnecessary steps, as well as including some changes necessary to fix broken links. The verbosity of the sphinx build jobs has been reduced so that only warnings and errors are shown, this will make diagnosing problems easier, and should speed up build times in the CI. Signed-off-by: Winford <winford@object.stream>

UncleGrumpy · 2024-02-07T04:44:48Z

I have moved the changes in the build system into a separate commit. I had not intended for this PR to be so large, but as I was making additions I realized the number of build errors had grown considerably, and some of the dead links needed to be corrected in the build system itself. I didn't want to flood the PR queue with doc related requests, and I was hoping to avoid merge conflicts.

In the future I will try to make these kinds of changes in separate PRs.

UncleGrumpy · 2024-02-10T22:57:26Z

I will be breaking this up and sending it to the release-0.6 branch.

UncleGrumpy force-pushed the documentation_updates branch from 7c34844 to bd2f271 Compare January 31, 2024 16:25

bettio requested changes Jan 31, 2024

View reviewed changes

UncleGrumpy added 3 commits January 31, 2024 22:32

Update README.Md

9fc71b1

Update links for build instructions on various platforms. Fixes several links in the Getting Started section that were places within parentheses, which led to undesireable formatting in the rendered text. Signed-off-by: Winford <winford@object.stream>

Corrections to source documentation

6caf319

Various typo corrections, add missing parmaters, and other format fixes for the API documentation generated from library source code files. Signed-off-by: Winford <winford@object.stream>

Revert to upstream edown

03a5190

The fix in uwiger/edown#30 has been merged upsteam, so we should now return to using the upstream tool available from hex. Removes unnecessary `ex_doc` plugin. Signed-off-by: Winford <winford@object.stream>

UncleGrumpy force-pushed the documentation_updates branch 4 times, most recently from 34d5dc4 to 0c2a7ff Compare February 1, 2024 18:55

fadushin approved these changes Feb 4, 2024

View reviewed changes

bettio reviewed Feb 5, 2024

View reviewed changes

UncleGrumpy force-pushed the documentation_updates branch from 0c2a7ff to 3a49789 Compare February 6, 2024 02:12

bettio reviewed Feb 6, 2024

View reviewed changes

UncleGrumpy added 2 commits February 6, 2024 16:30

Documentation updates

a74c614

Various corrections, formatting fixes, updates, and visual enhancements to the generated documentation. Signed-off-by: Winford <winford@object.stream>

UncleGrumpy force-pushed the documentation_updates branch from 3a49789 to 619d56c Compare February 7, 2024 04:04

UncleGrumpy closed this Feb 10, 2024

UncleGrumpy deleted the documentation_updates branch March 11, 2024 03:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation updates #1021

Documentation updates #1021

UncleGrumpy commented Jan 31, 2024 •

edited

Loading

bettio Jan 31, 2024

UncleGrumpy Feb 1, 2024

UncleGrumpy Feb 4, 2024

bettio Jan 31, 2024

UncleGrumpy Feb 1, 2024

fadushin left a comment

bettio Feb 5, 2024

UncleGrumpy Feb 6, 2024

UncleGrumpy Feb 6, 2024

bettio Feb 6, 2024

UncleGrumpy Feb 6, 2024

UncleGrumpy Feb 6, 2024 •

edited

Loading

bettio Feb 5, 2024

UncleGrumpy Feb 6, 2024

bettio Feb 6, 2024

UncleGrumpy Feb 6, 2024

bettio Feb 6, 2024

UncleGrumpy Feb 6, 2024

bettio commented Feb 6, 2024

UncleGrumpy commented Feb 6, 2024

UncleGrumpy commented Feb 7, 2024

UncleGrumpy commented Feb 10, 2024


		> Note: You should include a short `/* comment */` trailing the `#ifndef` entry mentioning the file where the function is actually documented.
		```{admonition} Note:

Documentation updates #1021

Documentation updates #1021

Conversation

UncleGrumpy commented Jan 31, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fadushin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

UncleGrumpy Feb 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bettio commented Feb 6, 2024

UncleGrumpy commented Feb 6, 2024

UncleGrumpy commented Feb 7, 2024

UncleGrumpy commented Feb 10, 2024

UncleGrumpy commented Jan 31, 2024 •

edited

Loading

UncleGrumpy Feb 6, 2024 •

edited

Loading