mirror of
https://github.com/roc-lang/roc.git
synced 2025-10-03 16:44:33 +00:00
Merge pull request #3277 from rtfeldman/fix-doc-comment-not-rendering
fix doc comment rendering
This commit is contained in:
Richard Feldman
GitHub
commit
72281e34d1
3 changed files with 37 additions and 24 deletions
|
|
@ -378,7 +378,7 @@ Int range : Num (Integer range)
|
|||
## access to hardware-accelerated performance, Roc follows these rules exactly.
|
||||
##
|
||||
## There's no literal syntax for these error values, but you can check to see if
|
||||
## you ended up with one of them by using [isNaN], [isFinite], and [isInfinite].
|
||||
## you ended up with one of them by using #isNaN, #isFinite, and #isInfinite.
|
||||
## Whenever a function in this module could return one of these values, that
|
||||
## possibility is noted in the function's documentation.
|
||||
##
|
||||
|
|
@ -1134,16 +1134,16 @@ toF64Checked : Num * -> Result F64 [OutOfBounds]*
|
|||
##
|
||||
## Always returns `True` when given a [Dec].
|
||||
##
|
||||
## This is the opposite of [isInfinite], except when given [*NaN*](Num.isNaN). Both
|
||||
## [isFinite] and [isInfinite] return `False` for [*NaN*](Num.isNaN).
|
||||
## This is the opposite of #isInfinite, except when given [*NaN*](Num.isNaN). Both
|
||||
## #isFinite and #isInfinite return `False` for [*NaN*](Num.isNaN).
|
||||
# isFinite : Frac * -> Bool
|
||||
## When given a [F64] or [F32] value, returns `True` if that value is either
|
||||
## ∞ or -∞, and `False` otherwise.
|
||||
##
|
||||
## Always returns `False` when given a [Dec].
|
||||
##
|
||||
## This is the opposite of [isFinite], except when given [*NaN*](Num.isNaN). Both
|
||||
## [isFinite] and [isInfinite] return `False` for [*NaN*](Num.isNaN).
|
||||
## This is the opposite of #isFinite, except when given [*NaN*](Num.isNaN). Both
|
||||
## #isFinite and #isInfinite return `False` for [*NaN*](Num.isNaN).
|
||||
# isInfinite : Frac * -> Bool
|
||||
## When given a [F64] or [F32] value, returns `True` if that value is
|
||||
## *NaN* ([not a number](https://en.wikipedia.org/wiki/NaN)), and `False` otherwise.
|
||||
|
|
@ -1166,7 +1166,7 @@ toF64Checked : Num * -> Result F64 [OutOfBounds]*
|
|||
##
|
||||
## Note that you should never put a *NaN* into a [Set], or use it as the key in
|
||||
## a [Dict]. The result is entries that can never be removed from those
|
||||
## collections! See the documentation for [Set.add] and [Dict.insert] for details.
|
||||
## collections! See the documentation for [Set.insert] and [Dict.insert] for details.
|
||||
# isNaN : Frac * -> Bool
|
||||
## Returns the higher of two numbers.
|
||||
##
|
||||
|
|
@ -1215,7 +1215,7 @@ toF64Checked : Num * -> Result F64 [OutOfBounds]*
|
|||
##
|
||||
## This is called `shlWrap` because any bits shifted
|
||||
## off the beginning of the number will be wrapped around to
|
||||
## the end. (In contrast, [shl] replaces discarded bits with zeroes.)
|
||||
## the end. (In contrast, #shl replaces discarded bits with zeroes.)
|
||||
# shlWrap : Int a, Int a -> Int a
|
||||
## [Logical bit shift](https://en.wikipedia.org/wiki/Bitwise_operation#Logical_shift) right.
|
||||
##
|
||||
|
|
@ -1225,7 +1225,7 @@ toF64Checked : Num * -> Result F64 [OutOfBounds]*
|
|||
##
|
||||
## This is called `shrWrap` because any bits shifted
|
||||
## off the end of the number will be wrapped around to
|
||||
## the beginning. (In contrast, [shr] replaces discarded bits with zeroes.)
|
||||
## the beginning. (In contrast, #shr replaces discarded bits with zeroes.)
|
||||
# shrWrap : Int a, Int a -> Int a
|
||||
# ## Convert a number into a [Str], formatted with the given options.
|
||||
# ##
|
||||
|
|
|
|||
|
|
@ -111,13 +111,13 @@ pub fn generate_module_docs(
|
|||
}
|
||||
|
||||
fn detached_docs_from_comments_and_new_lines<'a>(
|
||||
comments_or_new_lines: &'a [roc_parse::ast::CommentOrNewline<'a>],
|
||||
comments_or_new_lines: impl Iterator<Item = &'a roc_parse::ast::CommentOrNewline<'a>>,
|
||||
) -> Vec<String> {
|
||||
let mut detached_docs: Vec<String> = Vec::new();
|
||||
|
||||
let mut docs = String::new();
|
||||
|
||||
for comment_or_new_line in comments_or_new_lines.iter() {
|
||||
for comment_or_new_line in comments_or_new_lines {
|
||||
match comment_or_new_line {
|
||||
CommentOrNewline::DocComment(doc_str) => {
|
||||
docs.push_str(doc_str);
|
||||
|
|
@ -144,14 +144,22 @@ fn generate_entry_docs<'a>(
|
|||
use roc_parse::ast::Pattern;
|
||||
|
||||
let mut acc = Vec::with_capacity(defs.tags.len());
|
||||
let mut before_comments_or_new_lines = None;
|
||||
let mut before_comments_or_new_lines: Option<&[CommentOrNewline]> = None;
|
||||
let mut scratchpad = Vec::new();
|
||||
|
||||
for (index, either_index) in defs.tags.iter().enumerate() {
|
||||
let spaces_before = &defs.spaces[defs.space_before[index].indices()];
|
||||
|
||||
for detached_doc in detached_docs_from_comments_and_new_lines(spaces_before) {
|
||||
acc.push(DetachedDoc(detached_doc));
|
||||
}
|
||||
scratchpad.clear();
|
||||
scratchpad.extend(
|
||||
before_comments_or_new_lines
|
||||
.take()
|
||||
.iter()
|
||||
.flat_map(|e| e.iter()),
|
||||
);
|
||||
scratchpad.extend(spaces_before);
|
||||
|
||||
let docs = comments_or_new_lines_to_docs(&scratchpad);
|
||||
|
||||
match either_index.split() {
|
||||
Err(value_index) => match &defs.value_defs[value_index.index()] {
|
||||
|
|
@ -164,8 +172,7 @@ fn generate_entry_docs<'a>(
|
|||
name,
|
||||
type_annotation: type_to_docs(false, loc_ann.value),
|
||||
type_vars: Vec::new(),
|
||||
docs: before_comments_or_new_lines
|
||||
.and_then(comments_or_new_lines_to_docs),
|
||||
docs,
|
||||
};
|
||||
acc.push(DocEntry::DocDef(doc_def));
|
||||
}
|
||||
|
|
@ -184,8 +191,7 @@ fn generate_entry_docs<'a>(
|
|||
name: identifier.to_string(),
|
||||
type_annotation: type_to_docs(false, ann_type.value),
|
||||
type_vars: Vec::new(),
|
||||
docs: before_comments_or_new_lines
|
||||
.and_then(comments_or_new_lines_to_docs),
|
||||
docs,
|
||||
};
|
||||
acc.push(DocEntry::DocDef(doc_def));
|
||||
}
|
||||
|
|
@ -213,7 +219,7 @@ fn generate_entry_docs<'a>(
|
|||
name: name.value.to_string(),
|
||||
type_annotation: type_to_docs(false, ann.value),
|
||||
type_vars,
|
||||
docs: before_comments_or_new_lines.and_then(comments_or_new_lines_to_docs),
|
||||
docs,
|
||||
};
|
||||
acc.push(DocEntry::DocDef(doc_def));
|
||||
}
|
||||
|
|
@ -234,7 +240,7 @@ fn generate_entry_docs<'a>(
|
|||
name: name.value.to_string(),
|
||||
type_annotation: TypeAnnotation::NoTypeAnn,
|
||||
type_vars,
|
||||
docs: before_comments_or_new_lines.and_then(comments_or_new_lines_to_docs),
|
||||
docs,
|
||||
};
|
||||
acc.push(DocEntry::DocDef(doc_def));
|
||||
}
|
||||
|
|
@ -272,14 +278,21 @@ fn generate_entry_docs<'a>(
|
|||
name: name.value.to_string(),
|
||||
type_annotation: TypeAnnotation::Ability { members },
|
||||
type_vars,
|
||||
docs: before_comments_or_new_lines.and_then(comments_or_new_lines_to_docs),
|
||||
docs,
|
||||
};
|
||||
acc.push(DocEntry::DocDef(doc_def));
|
||||
}
|
||||
},
|
||||
}
|
||||
|
||||
before_comments_or_new_lines = Some(&defs.spaces[defs.space_after[index].indices()]);
|
||||
let spaces_after = &defs.spaces[defs.space_after[index].indices()];
|
||||
before_comments_or_new_lines = Some(spaces_after);
|
||||
}
|
||||
|
||||
let it = before_comments_or_new_lines.iter().flat_map(|e| e.iter());
|
||||
|
||||
for detached_doc in detached_docs_from_comments_and_new_lines(it) {
|
||||
acc.push(DetachedDoc(detached_doc));
|
||||
}
|
||||
|
||||
acc
|
||||
|
|
|
|||
|
|
@ -749,8 +749,8 @@ fn doc_url<'a>(
|
|||
Err(_) => {
|
||||
// TODO return Err here
|
||||
panic!(
|
||||
"Tried to generate an automatic link in docs for symbol `{}`, but that symbol was not in scope in this module. Scope was: {:?}",
|
||||
ident, scope
|
||||
"Tried to generate an automatic link in docs for symbol `{}`, but that symbol was not in scope in this module.",
|
||||
ident
|
||||
);
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue