capi: Documentation cleanup #664
Conversation
|
Question: do we need to mention that it supports only ASCII-subset of UTF-8 for names, or is it obvious from the fact that |
Codecov Report
@@ Coverage Diff @@
## master #664 +/- ##
=======================================
Coverage 99.27% 99.27%
=======================================
Files 71 71
Lines 9853 9853
=======================================
Hits 9782 9782
Misses 71 71
Flags with carried forward coverage won't be shown. Click here to find out more. |
include/fizzy/fizzy.h
Outdated
| /// imported_globals_size equals 0. | ||
| /// @param imported_globals_size Size of the imported global array. Can be zero. | ||
| /// @returns non-NULL pointer to instance in case of success, NULL otherwise. | ||
| /// @param module Pointer to module. Cannot be NULL. |
There was a problem hiding this comment.
Are we also keeping some specific width between @param and the name? We could say that and do it in the other PR too (#528).
There was a problem hiding this comment.
I keep one space because this looks like a "command" @param name and this is always aligned.
| @@ -32,10 +32,10 @@ typedef struct FizzyExecutionResult | |||
| { | |||
| /// Whether execution ended with a trap. | |||
| bool trapped; | |||
| /// Whether function returned a value. Valid only if trapped equals false. | |||
| /// Whether function returned a value. | |||
| bool has_value; | |||
There was a problem hiding this comment.
So if we make this ambiguous here, why don't we state that if trapped = false, the other fields are undefined behaviour.
There was a problem hiding this comment.
I don't see this ambiguous. This is false if trapped == true. You can add this in the description.
include/fizzy/fizzy.h
Outdated
| /// defined in module. Behaviour is undefined, if index is not valid according to | ||
| /// module definition. | ||
| /// @param module Pointer to module. Cannot be NULL. | ||
| /// @param func_idx Function index. Can be either index of an imported function or of a function |
There was a problem hiding this comment.
IMHO it is fine to just keep <=2 spaces between param name and description.
There was a problem hiding this comment.
I agree, vote for 2 spaces.
Also #664 (comment) ^^
There was a problem hiding this comment.
Changed both widths.
There was a problem hiding this comment.
Oh sorry, I meant the 2 spaces for between @param and module, and 4 spaces between module and Pointer to module 😬
There was a problem hiding this comment.
What is the point of additional fucking spaces?
There was a problem hiding this comment.
It was the style @gumb0 used half time and I found it rather readable. I don't care whatever is the decision as long as it is consistent.
There was a problem hiding this comment.
I think it looks more readable when it's a bit more spaced out.
(what I originally used was starting comments on tab positions)
gumb0
force-pushed
the
capi-comment-cleanup
branch
3 times, most recently
from
6e5e2ae
to
c1f7355
Compare
gumb0
force-pushed
the
capi-comment-cleanup
branch
from
c1f7355
to
dd5ca27
Compare
gumb0
force-pushed
the
capi-comment-cleanup
branch
from
dd5ca27
to
1b81853
Compare
No description provided.