language-servers/roc
1
0
Fork 0
mirror of https://github.com/roc-lang/roc.git synced 2025-10-03 16:44:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

Merge pull request #3277 from rtfeldman/fix-doc-comment-not-rendering

Browse source 
fix doc comment rendering
This commit is contained in:
Richard Feldman 2022-06-21 16:06:06 -04:00 • committed by GitHub
commit 72281e34d1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 37 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

16
compiler/builtins/roc/Num.roc
View file

@ -378,7 +378,7 @@ Int range : Num (Integer range)
## access to hardware-accelerated performance, Roc follows these rules exactly. ## 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 ## 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 ## Whenever a function in this module could return one of these values, that
## possibility is noted in the function's documentation. ## possibility is noted in the function's documentation.
## ##
@ -1134,16 +1134,16 @@ toF64Checked : Num * -> Result F64 [OutOfBounds]*
## ##
## Always returns `True` when given a [Dec]. ## Always returns `True` when given a [Dec].
## ##
## This is the opposite of [isInfinite], except when given [*NaN*](Num.isNaN). Both ## This is the opposite of #isInfinite, except when given [*NaN*](Num.isNaN). Both
## [isFinite] and [isInfinite] return `False` for [*NaN*](Num.isNaN). ## #isFinite and #isInfinite return `False` for [*NaN*](Num.isNaN).
# isFinite : Frac * -> Bool # isFinite : Frac * -> Bool
## When given a [F64] or [F32] value, returns `True` if that value is either ## When given a [F64] or [F32] value, returns `True` if that value is either
## ∞ or -∞, and `False` otherwise. ## ∞ or -∞, and `False` otherwise.
## ##
## Always returns `False` when given a [Dec]. ## Always returns `False` when given a [Dec].
## ##
## This is the opposite of [isFinite], except when given [*NaN*](Num.isNaN). Both ## This is the opposite of #isFinite, except when given [*NaN*](Num.isNaN). Both
## [isFinite] and [isInfinite] return `False` for [*NaN*](Num.isNaN). ## #isFinite and #isInfinite return `False` for [*NaN*](Num.isNaN).
# isInfinite : Frac * -> Bool # isInfinite : Frac * -> Bool
## When given a [F64] or [F32] value, returns `True` if that value is ## 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. ## *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 ## 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 ## 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 # isNaN : Frac * -> Bool
## Returns the higher of two numbers. ## Returns the higher of two numbers.
## ##
@ -1215,7 +1215,7 @@ toF64Checked : Num * -> Result F64 [OutOfBounds]*
## ##
## This is called `shlWrap` because any bits shifted ## This is called `shlWrap` because any bits shifted
## off the beginning of the number will be wrapped around to ## 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 # shlWrap : Int a, Int a -> Int a
## [Logical bit shift](https://en.wikipedia.org/wiki/Bitwise_operation#Logical_shift) right. ## [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 ## This is called `shrWrap` because any bits shifted
## off the end of the number will be wrapped around to ## 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 # shrWrap : Int a, Int a -> Int a
# ## Convert a number into a [Str], formatted with the given options. # ## Convert a number into a [Str], formatted with the given options.
# ## # ##

41
compiler/load_internal/src/docs.rs
View file

@ -111,13 +111,13 @@ pub fn generate_module_docs(
} }
fn detached_docs_from_comments_and_new_lines<'a>( 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> { ) -> Vec<String> {
let mut detached_docs: Vec<String> = Vec::new(); let mut detached_docs: Vec<String> = Vec::new();
let mut docs = String::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 { match comment_or_new_line {
CommentOrNewline::DocComment(doc_str) => { CommentOrNewline::DocComment(doc_str) => {
docs.push_str(doc_str); docs.push_str(doc_str);
@ -144,14 +144,22 @@ fn generate_entry_docs<'a>(
use roc_parse::ast::Pattern; use roc_parse::ast::Pattern;
let mut acc = Vec::with_capacity(defs.tags.len()); 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() { for (index, either_index) in defs.tags.iter().enumerate() {
let spaces_before = &defs.spaces[defs.space_before[index].indices()]; let spaces_before = &defs.spaces[defs.space_before[index].indices()];
for detached_doc in detached_docs_from_comments_and_new_lines(spaces_before) { scratchpad.clear();
acc.push(DetachedDoc(detached_doc)); 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() { match either_index.split() {
Err(value_index) => match &defs.value_defs[value_index.index()] { Err(value_index) => match &defs.value_defs[value_index.index()] {
@ -164,8 +172,7 @@ fn generate_entry_docs<'a>(
name, name,
type_annotation: type_to_docs(false, loc_ann.value), type_annotation: type_to_docs(false, loc_ann.value),
type_vars: Vec::new(), type_vars: Vec::new(),
docs: before_comments_or_new_lines docs,
.and_then(comments_or_new_lines_to_docs),
}; };
acc.push(DocEntry::DocDef(doc_def)); acc.push(DocEntry::DocDef(doc_def));
} }
@ -184,8 +191,7 @@ fn generate_entry_docs<'a>(
name: identifier.to_string(), name: identifier.to_string(),
type_annotation: type_to_docs(false, ann_type.value), type_annotation: type_to_docs(false, ann_type.value),
type_vars: Vec::new(), type_vars: Vec::new(),
docs: before_comments_or_new_lines docs,
.and_then(comments_or_new_lines_to_docs),
}; };
acc.push(DocEntry::DocDef(doc_def)); acc.push(DocEntry::DocDef(doc_def));
} }
@ -213,7 +219,7 @@ fn generate_entry_docs<'a>(
name: name.value.to_string(), name: name.value.to_string(),
type_annotation: type_to_docs(false, ann.value), type_annotation: type_to_docs(false, ann.value),
type_vars, type_vars,
docs: before_comments_or_new_lines.and_then(comments_or_new_lines_to_docs), docs,
}; };
acc.push(DocEntry::DocDef(doc_def)); acc.push(DocEntry::DocDef(doc_def));
} }
@ -234,7 +240,7 @@ fn generate_entry_docs<'a>(
name: name.value.to_string(), name: name.value.to_string(),
type_annotation: TypeAnnotation::NoTypeAnn, type_annotation: TypeAnnotation::NoTypeAnn,
type_vars, type_vars,
docs: before_comments_or_new_lines.and_then(comments_or_new_lines_to_docs), docs,
}; };
acc.push(DocEntry::DocDef(doc_def)); acc.push(DocEntry::DocDef(doc_def));
} }
@ -272,14 +278,21 @@ fn generate_entry_docs<'a>(
name: name.value.to_string(), name: name.value.to_string(),
type_annotation: TypeAnnotation::Ability { members }, type_annotation: TypeAnnotation::Ability { members },
type_vars, type_vars,
docs: before_comments_or_new_lines.and_then(comments_or_new_lines_to_docs), docs,
}; };
acc.push(DocEntry::DocDef(doc_def)); 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 acc

4
docs/src/lib.rs
View file

@ -749,8 +749,8 @@ fn doc_url<'a>(
Err(_) => { Err(_) => {
// TODO return Err here // TODO return Err here
panic!( panic!(
"Tried to generate an automatic link in docs for symbol `{}`, but that symbol was not in scope in this module. Scope was: {:?}", "Tried to generate an automatic link in docs for symbol `{}`, but that symbol was not in scope in this module.",
ident, scope ident
); );
} }
} }