Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consolidate Oak ABI documentation #877

Closed
tiziano88 opened this issue Apr 20, 2020 · 2 comments
Closed

Consolidate Oak ABI documentation #877

tiziano88 opened this issue Apr 20, 2020 · 2 comments
Assignees

Comments

@tiziano88
Copy link
Collaborator

Currently the documentation of ABI-level functions is partially replicated in various places. In some cases it makes sense for it to be more precise in the context of a particular object or programming language, but I wonder whether we can do a better job at least at cross-referencing these various pieces together.

For instance, for the node_create call:

Runtime object:

/// Thread safe method that attempts to create a Node within the [`Runtime`] corresponding to a
/// given module name and entrypoint. The `reader: ChannelReader` is passed to the newly
/// created Node.
///
/// The caller also specifies a [`Label`], which is assigned to the newly created Node. See
/// <https://github.com/project-oak/oak/blob/master/docs/concepts.md#labels> for more
/// information on labels.
///
/// This method is defined on [`Arc`] and not [`Runtime`] itself, so that
/// the [`Arc`] can clone itself and be included in a [`RuntimeProxy`] object
/// to be given to a new Node.
pub fn node_create(

oak_abi crate:

/// Create a new Node instance running code identified by configuration
/// name and entrypoint; the entrypoint is only used when creating a
/// WebAssembly Node; it is ignored when creating a pseudo-Node.
///
/// The configuration name is provided in the memory area given by
/// `config_buf` and `config_len`; the entrypoint name is provided in the
/// memory area given by `entrypoint_buf` and `entrypoint_len`.
///
/// Returns the status of the operation, as an [`OakStatus`] value.
///
/// [`OakStatus`]: crate::OakStatus
pub fn node_create(

Oak ABI documentation:

https://github.com/project-oak/oak/blob/bc98624bdcf6629c4f3ef4aa139bd4a0892f3744/docs/abi.md#node_create

@daviddrysdale do you have any ideas / suggestions?

@daviddrysdale
Copy link
Contributor

Is this the same as #812 ?

tiziano88 added a commit to tiziano88/oak that referenced this issue May 12, 2020
I was tired of trying to keep the parameter numbers in sync :)

Ref project-oak#877
tiziano88 added a commit to tiziano88/oak that referenced this issue May 12, 2020
I was tired of trying to keep the parameter numbers in sync :)

Fix ABI documentation to not repeat types, and use terminology more in
line with standard WebAssembly (see
https://hacks.mozilla.org/2019/11/multi-value-all-the-wasm/ for the
choice of `param` and `result` in particular).

Ref project-oak#877
tiziano88 added a commit to tiziano88/oak that referenced this issue May 12, 2020
I was tired of trying to keep the parameter numbers in sync :)

Fix ABI documentation to not repeat types, and use terminology more in
line with standard WebAssembly (see
https://hacks.mozilla.org/2019/11/multi-value-all-the-wasm/ for the
choice of `param` and `result` in particular).

Ref project-oak#877
tiziano88 added a commit that referenced this issue May 12, 2020
I was tired of trying to keep the parameter numbers in sync :)

Fix ABI documentation to not repeat types, and use terminology more in
line with standard WebAssembly (see
https://hacks.mozilla.org/2019/11/multi-value-all-the-wasm/ for the
choice of `param` and `result` in particular).

Ref #877
@daviddrysdale
Copy link
Contributor

Some of the duplicate comments have been removed (two copies dropped in #883, one in #979).

Current places that describe ABI functions, using node_create as an example:

De-duped enough?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants