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

Use markdown instead of ocamldoc for docblock comment #5095

Merged
merged 18 commits into from
Apr 26, 2021

Conversation

chenglou
Copy link
Member

@chenglou chenglou commented Apr 25, 2021

  • Safe change. Just comments.
  • Odoc throws exception for certain snippets; this causes the editor plugin to fail to display the code block. Now we're just gonna pass through the raw markdown block to be displayed.
  • More familiar with the JS audience (and most other folks really).

I've converted over:

  • [foo]
  • @example [{...}] and miscellaneous blocks
  • ul, ol
  • {b boldStuff}
  • {i italicStuff}
  • {%html} blocks
  • Things that don't need escape anymore, e.g. \[\@\@module\]
  • @return -> **return**. Same for @param, @raise and @since.
  • Use markdown link for @see.
  • 2 indentations instead of 4, since 4 means a code block in markdown.
  • Double newline for a rendered newline (markdown single newline doesn't break line in output).

@chenglou
Copy link
Member Author

I'll squash merge once this is approved, to avoid noisy commits

@chenglou
Copy link
Member Author

Some regex personal notes for posteriority:

([^{])\[([^%|@\\].*?)]

revert:
\[
`.{1,3};.+
`]
\`
`\

check more:
\@
[^\[@]@[^@]       <- check also
`@       <- check also
\{[a-zA-Z]  <- {b Unsafe}, {!head} and others
  like \{b (.+?)\}
@example {[ <- check also
{%html:
@return
@raise
@param
@since
@see
{!Belt.Array}
MDN links

bobzhang pushed a commit that referenced this pull request Apr 26, 2021
- Safe change. Just comments.
- Odoc throws exception for certain snippets; this causes the editor plugin to fail to display the code block. Now we're just gonna pass through the raw markdown block to be displayed.
- More familiar with the JS audience (and most other folks really).

I've converted over:
- `[foo]`
- `@example [{...}]` and miscellaneous  blocks
- `ul`, `ol`
- `{b boldStuff}`
- `{i italicStuff}`
- `{%html}` blocks
- Things that don't need escape anymore, e.g. `\[\@\@module\]`
- `@return` -> `**return**`. Same for `@param`, `@raise` and `@since`.
- Use markdown link for `@see`.
- 2 indentations instead of 4, since 4 means a code block in markdown.
- Double newline for a rendered newline (markdown single newline doesn't break line in output).
bobzhang pushed a commit that referenced this pull request Jun 20, 2021
- Safe change. Just comments.
- Odoc throws exception for certain snippets; this causes the editor plugin to fail to display the code block. Now we're just gonna pass through the raw markdown block to be displayed.
- More familiar with the JS audience (and most other folks really).

I've converted over:
- `[foo]`
- `@example [{...}]` and miscellaneous  blocks
- `ul`, `ol`
- `{b boldStuff}`
- `{i italicStuff}`
- `{%html}` blocks
- Things that don't need escape anymore, e.g. `\[\@\@module\]`
- `@return` -> `**return**`. Same for `@param`, `@raise` and `@since`.
- Use markdown link for `@see`.
- 2 indentations instead of 4, since 4 means a code block in markdown.
- Double newline for a rendered newline (markdown single newline doesn't break line in output).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants