API documentation is missing an explanation of CMARK_NODE_CUSTOM_BLOCK and CMARK_NODE_CUSTOM_INLINE
Nobody has claimed this yet.
- Dominant language
- C
- Stars
- 2k
- Forks
- 691
- Avg merge
- 1d 16h
- Merged PRs (30d)
- 1
Description
The API documentation for cmark (e.g. in the cmark.3 man page) does not explain the
purpose or proper use of the CMARK_NODE_CUSTOM_BLOCK and CMARK_NODE_HTML_INLINE constants from the cmark_node_type enum. (Actually, it does not explain the purpose or use of any of the cmark_node_type constants; but all the others correspond fairly obviously to blocks or inlines in the CommonMark spec.)
I see that the changelog contains some description of them:
- [API change] Added
CUSTOM_BLOCKandCUSTOM_INLINEnode types.
They are never generated by the parser, and do not correspond
to CommonMark elements. They are designed to be inserted by
filters that postprocess the AST. For example, a filter might
convert specially marked code blocks to svg diagrams in HTML
and tikz diagrams in LaTeX, passing these through to the renderer
as aCUSTOM_BLOCK. These nodes can have children, but they
also have literal text to be printed by the renderer "on enter"
and "on exit." Addedcmark_node_get_on_enter,
cmark_node_set_on_enter,cmark_node_get_on_exit,
cmark_node_set_on_exitto API.
But that information really should be in the API documentation, not in the changelog - without it, the API documentation cannot be understood. And because the changelog uses the abbreviation CUSTOM_BLOCK instead of spelling out CMARK_NODE_CUSTOM_BLOCK in full, searching for CMARK_NODE_CUSTOM_BLOCK in the repository will never bring up that changelog entry, making it difficult for developers to work out what it was intended to do.
If the man page is the only place that would need updating, then I'd be happy to create a PR to add the changelog information to the man page, if desired.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with man/man3/cmark.3 and locate the cmark_node_type and custom-node API documentation, then compare it with the relevant entry in changelog.txt. Done means the documentation explains that CMARK_NODE_CUSTOM_BLOCK and CMARK_NODE_CUSTOM_INLINE are inserted by filters, are not generated by the parser, and describes their children, literal text, and on-enter/on-exit behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100