Stream: git-wasmtime

Topic: wasmtime / PR #1928 Add support for documenting the C API

Wasmtime GitHub notifications bot (Jun 26 2020 at 16:01):

alexcrichton opened PR #1928 from c-api-docs to main:

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.

Wasmtime GitHub notifications bot (Jun 26 2020 at 16:01):

alexcrichton submitted PR Review.

Wasmtime GitHub notifications bot (Jun 26 2020 at 16:01):

alexcrichton created PR Review Comment:

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.

Wasmtime GitHub notifications bot (Jun 26 2020 at 16:02):

alexcrichton updated PR #1928 from c-api-docs to main:

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.

Wasmtime GitHub notifications bot (Jun 26 2020 at 16:06):

alexcrichton updated PR #1928 from c-api-docs to main:

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.

Wasmtime GitHub notifications bot (Jun 26 2020 at 16:07):

alexcrichton updated PR #1928 from c-api-docs to main:

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.

Wasmtime GitHub notifications bot (Jun 26 2020 at 16:08):

alexcrichton updated PR #1928 from c-api-docs to main:

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.

Wasmtime GitHub notifications bot (Jun 26 2020 at 16:11):

alexcrichton updated PR #1928 from c-api-docs to main:

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.

Wasmtime GitHub notifications bot (Jun 26 2020 at 16:14):

alexcrichton updated PR #1928 from c-api-docs to main:

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.

Wasmtime GitHub notifications bot (Jul 01 2020 at 18:51):

kubkon submitted PR Review.

Wasmtime GitHub notifications bot (Jul 01 2020 at 19:05):

alexcrichton merged PR #1928.

Last updated: Nov 22 2024 at 16:03 UTC