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

Add support for documenting the C API #1928

Merged
merged 1 commit into from
Jul 1, 2020

Conversation

alexcrichton
Copy link
Member

This commit adds a bit of a skeleton of what it might look like to
document the C API. Today the C API has virtually zero documentation
because the upstream documentation does not exist and we haven't put a
ton of effort into documenting our own extensions. Given that this is
one of the main vectors we expect users to use Wasmtime, we should make
sure it's thoroughly documented!

I've never really done much documentation generation of C myself before,
but I did a bit of searching and Doxygen seems reasonable proficient for
doing this. This commit sets up what it might look like for Doxygen to
be used for the C API. One nice feature of DOxygen is that we can
document the items in wasm.h without actually modifying wasm.h. For
those purposes a doc-wasm.h file was added here which is where we can
put Wasmtime-specific documentation about wasm.h.

There's quite a few functions in the C API so I didn't want to get them
all done before getting consensus on this. I've started some skeletons
of documentation for global types in wasm.h and also confirmed that
documentation works for our own wasmtime.h and such header files. If
this looks good to everyone and it runs reasonable well on CI then I can
spend more time filling out the rest of the documentation.

@@ -0,0 +1,2538 @@
# Doxyfile 1.8.17
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's worth pointing out that I generated this file with doxygen -f doxygen.conf. I've tweaked a number of settings internally but I'm hoping that most of this file can basically be ignored.

@alexcrichton alexcrichton force-pushed the c-api-docs branch 5 times, most recently from 5d7979f to f04b9bf Compare June 26, 2020 16:10
This commit adds a bit of a skeleton of what it might look like to
document the C API. Today the C API has virtually zero documentation
because the upstream documentation does not exist and we haven't put a
ton of effort into documenting our own extensions. Given that this is
one of the main vectors we expect users to use Wasmtime, we should make
sure it's thoroughly documented!

I've never really done much documentation generation of C myself before,
but I did a bit of searching and Doxygen seems reasonable proficient for
doing this. This commit sets up what it might look like for Doxygen to
be used for the C API. One nice feature of DOxygen is that we can
document the items in `wasm.h` without actually modifying `wasm.h`. For
those purposes a `doc-wasm.h` file was added here which is where we can
put Wasmtime-specific documentation about `wasm.h`.

There's quite a few functions in the C API so I didn't want to get them
all done before getting consensus on this. I've started some skeletons
of documentation for global types in `wasm.h` and also confirmed that
documentation works for our own `wasmtime.h` and such header files. If
this looks good to everyone and it runs reasonable well on CI then I can
spend more time filling out the rest of the documentation.
@github-actions github-actions bot added the wasmtime:c-api Issues pertaining to the C API. label Jun 26, 2020
@github-actions
Copy link

Subscribe to Label Action

cc @peterhuene

This issue or pull request has been labeled: "wasmtime:c-api"

Thus the following users have been cc'd because of the following labels:

  • peterhuene: wasmtime:c-api

To subscribe or unsubscribe from this label, edit the .github/subscribe-to-label.json configuration file.

Learn more.

@tschneidereit
Copy link
Member

This seems great to me! (Apart from the preposterously large config file, but I saw your comment about that, and oh well 🙃)

One question: do you expect people to find this via a link from the overall Wasmtime docs, or do you plan to add a link to it somewhere else?

@alexcrichton
Copy link
Member Author

The intention is that this will be available (once merged) at https://bytecodealliance.github.io/wasmtime/c-api/ (similar to https://bytecodealliance.github.io/wasmtime/api/wasmtime/ for Rust). I'd imagine we'd update our documentation to link to that, such as:

I'm also hoping that we can use this to help drive forward adding documentation to the upstream API when it's appropriate.

@tschneidereit
Copy link
Member

@alexcrichton ok, that all sounds great to me! It probably makes sense to get a review from someone better capable of actually evaluating the technical parts, but as an approach, this looks great to me!

@kubkon
Copy link
Member

kubkon commented Jul 1, 2020

FWIW, IMHO this is an excellent effort, thanks @alexcrichton!

Copy link
Member

@kubkon kubkon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! I'm guessing that the rest of wasmtime.h docs will be added as we go, right? Also, IMHO this is a huge game changer for embedding wasmtime in different languages. FWIW, I wish it was there when I was drafting out the basics of wasmtime-zig! So huge thanks @alexcrichton!

@alexcrichton
Copy link
Member Author

Thanks for taking a look @kubkon! And yeah I've actually got everything else filled out, which I'll post as a PR next

@alexcrichton alexcrichton merged commit d72b330 into bytecodealliance:main Jul 1, 2020
@alexcrichton alexcrichton deleted the c-api-docs branch July 1, 2020 19:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
wasmtime:c-api Issues pertaining to the C API.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants