Fix broken method and type headings in generated documentation #2262
Conversation
src/libponyc/pass/docgen.c
Outdated
| @@ -796,7 +796,7 @@ static void doc_entity(docgen_t* docgen, docgen_opt_t* docgen_opt, ast_t* ast) | |||
|
|
|||
| // Now we can write the actual documentation for the entity | |||
| fprintf(docgen->type_file, "# %s", name); | |||
| doc_type_params(docgen, docgen_opt, tparams, true); | |||
| doc_type_params(docgen, docgen_opt, tparams, true, true); | |||
There was a problem hiding this comment.
we need a false here, since those type params are part of a markdown heading
There was a problem hiding this comment.
E.g. the title of the collections.Range docs is still line-broken
There was a problem hiding this comment.
You're right! This is a slightly different, but of course related, bug: I've just found an instance of it in the Flag docs.
Thanks, will update. 👍
There was a problem hiding this comment.
(Oh I should have reloaded my page -- didn't see your second comment when adding mine. Anyhow, you're right. It's updated.)
srenatus
force-pushed
the
docgen/no-line-breaks-for-headers
branch
from
85dea45 to
3fdc6ce
Compare
src/libponyc/pass/docgen.c
Outdated
| @@ -344,7 +344,7 @@ static const char* doc_get_cap(ast_t* cap) | |||
|
|
|||
| // Write the given type to the current type file | |||
| static void doc_type(docgen_t* docgen, docgen_opt_t* docgen_opt, | |||
| ast_t* type, bool generate_links) | |||
| ast_t* type, bool generate_links, bool break_union_lines) | |||
There was a problem hiding this comment.
maybe we want to rename this to break_linkes as it does not only apply to union types and would be more consistent with the existing functions.
There was a problem hiding this comment.
hmm yeah... it's a bit odd there. I initially only wanted it to apply to union, but then I've found that's getting threaded through the other types... so, yeah, where this ended up in, it makes more sense to call it break_lines.
|
Oh yeah! i came across this nuisance several times. Thank you for tackling this! |
Before, many `from()` methods' docs were broken, because markdown
doesn't allow you to have line breaks in your headers, e.g.
### from[A: ((I8 val | I16 val | I32 val |
[I64](builtin-I64) val | [I128](builtin-I128) val | [ILong](builtin-ILong) val |
Now, it'll not insert breaks for unions (introduced in ponylang#1294) when it is
a method header, but leaves it as one long line. (It certainly isn't
beautiful, but it is less broken...)
Turns out this bug has another instance in document headers:
# Flag\[A: (([U8](builtin-U8) val | [U16](builtin-U16) val | [U32](builtin-U32) val |
[U64](builtin-U64) val | [U128](builtin-U128) val | [ULong](builtin-ULong) val |
...will also be one long line now.
Also renames an existing `line_breaks` argument to `break_lines` to be
in-line with `generate_links`.
Signed-off-by: Stephan Renatus <[email protected]>
srenatus
force-pushed
the
docgen/no-line-breaks-for-headers
branch
from
3fdc6ce to
e526c07
Compare
mfelsche
added
the
changelog - fixed
mfelsche
changed the title
|
@srenatus I added the "changelog - fixed" and edited the title for the changelog. |
|
Thank you very much! |
Before, many
from()methods' docs were broken, because markdowndoesn't allow you to have line breaks in your headers, e.g.
Now, it'll not insert breaks for unions (introduced in #1294) when it is
a method header, but leaves it as one long line. (It certainly isn't
beautiful, but it is less broken...)
Turns out this bug has another instance in document headers:
...will also be one long line now.
Before:
After:
