Skip to content

Commit

Permalink
fix(fluxdoc): adds support for a _soft_ paragraph
Browse files Browse the repository at this point in the history 
It is possible for a list item in Markdown to have multiple lines and
also not be a _paragraph_. I am calling these _soft_ paragraphs, this
change adds support to the parameter parsing to consume these _soft_
paragraphs as the entire headline.
  • Loading branch information
@nathanielc
nathanielc committed Apr 6, 2022
1 parent 645e5f4 commit 0ebd453
Show file tree
Hide file tree
Showing 6 changed files with 160 additions and 15 deletions.
Binary file modified embed/stdlib/contrib/bonitoo-io/servicenow.fc
View file
Binary file not shown.
Binary file modified embed/stdlib/contrib/sranka/opsgenie.fc
View file
Binary file not shown.
163 changes: 153 additions & 10 deletions libflux/flux-core/src/doc/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -970,28 +970,33 @@ impl<'a> Parser<'a> {
}
fn parse_parameter_headline(&mut self) -> Result<()> {
let mut range = Range::<usize> { start: 0, end: 0 };
// We will either have a paragraph or a single text node
// We will either have a paragraph or content within the entire item.
match self.iter.next() {
Some((Event::Start(Tag::Paragraph), r)) => {
range.start = r.start;
}
Some((Event::Text(_), r)) => {
self.tokens.push(Token::ParamHeadline(self.slice(r)));
return self.parse_parameter_description();
}
_ => {
// We didn't find a good headline
// Find the end of the item and start over
Some((_, start)) => {
// We do not have an explicit paragraph so assume the entire item is the headline.
loop {
match self.iter.next() {
Some((Event::End(Tag::Item), _)) => {
return self.parse_any_heading_or_description()
Some((Event::End(Tag::Item), end)) => {
self.tokens.push(Token::ParamHeadline(self.slice(Range {
start: start.start,
end: end.end,
})));
// Parse the next parameter
return self.parse_parameter();
}
Some((Event::Start(Tag::Item), _)) => {
// We found a new list within the headline we should bail with a helpful message.
bail!("found a new list within a parameter headline. Use a new paragraph to separate the list from the headline.")
}
Some(_) => {}
None => bail!("reached end of markdown without reaching end of item"),
};
}
}
None => bail!("reached end of markdown without reaching end of item"),
};
// We have a paragraph so gather all events until the end of the paragraph.
loop {
Expand Down Expand Up @@ -1294,6 +1299,77 @@ mod test {
);
}
#[test]
fn test_value_doc_multiline_headline_no_desc() {
let src = "
// Package foo does a thing.
package foo
// a is a constant. This headline has `code`
// and multiple lines.
a = 1
";
let loc = Locator::new(&src[..]);
assert_docs_full(
src,
PackageDoc {
path: "path".to_string(),
name: "foo".to_string(),
headline: "Package foo does a thing.".to_string(),
description: None,
members: map![
"a" => Doc::Value(Box::new(ValueDoc{
name: "a".to_string(),
headline: "a is a constant. This headline has `code`\nand multiple lines.".to_string(),
description: None,
flux_type: "int".to_string(),
is_option: false,
source_location: loc.get(7,9,7,14),
examples: vec![],
metadata: None,
})),
],
examples: Vec::new(),
metadata: None,
},
vec![],
);
}
#[test]
fn test_value_doc_code_headline_no_desc() {
let src = "
// Package foo does a thing.
package foo
// a is a constant. This headline has `code`.
a = 1
";
let loc = Locator::new(&src[..]);
assert_docs_full(
src,
PackageDoc {
path: "path".to_string(),
name: "foo".to_string(),
headline: "Package foo does a thing.".to_string(),
description: None,
members: map![
"a" => Doc::Value(Box::new(ValueDoc{
name: "a".to_string(),
headline: "a is a constant. This headline has `code`.".to_string(),
description: None,
flux_type: "int".to_string(),
is_option: false,
source_location: loc.get(6,9,6,14),
examples: vec![],
metadata: None,
})),
],
examples: Vec::new(),
metadata: None,
},
vec![],
);
}
#[test]
fn test_value_doc_headline_invalid() {
let src = "
// Package foo does a thing.
Expand Down Expand Up @@ -1887,6 +1963,73 @@ foo.a
);
}
#[test]
fn test_function_doc_multiline() {
// It is possible in markdown for a list item to contain mutliple lines without
// having an explicit paragraph tag, this test case validates that such soft paragraphs are
// correctly captured into the headline.

let src = "
// Package foo does a thing.
package foo
// f is a function
//
// ## Parameters
// - a: parameter with a multiline
// headline without a paragraph.
// - b: parameter with `code` and a multiline
// headline without a paragraph.
// - c: parameter with a multiline
// headline without a paragraph but with `code`.
f = (a, b, c) => 1
";
let loc = Locator::new(&src[..]);
assert_docs_full(
src,
PackageDoc {
path: "path".to_string(),
name: "foo".to_string(),
headline: "Package foo does a thing.".to_string(),
description: None,
members: map![
"f" => Doc::Function(Box::new(FunctionDoc{
name: "f".to_string(),
headline: "f is a function".to_string(),
description: None,
parameters: vec![
ParameterDoc{
name: "a".to_string(),
headline: "a: parameter with a multiline\n headline without a paragraph.".to_string(),
description: None,
required: true,
},
ParameterDoc{
name: "b".to_string(),
headline: "b: parameter with `code` and a multiline\n headline without a paragraph.".to_string(),
description: None,
required: true,
},
ParameterDoc{
name: "c".to_string(),
headline: "c: parameter with a multiline\n headline without a paragraph but with `code`.".to_string(),
description: None,
required: true,
},
],
flux_type: "(a:A, b:B, c:C) => int".to_string(),
is_option: false,
source_location: loc.get(14,9,14,27),
examples: vec![],
metadata: None,
})),
],
examples: Vec::new(),
metadata: None,
},
vec![],
);
}
#[test]
fn test_function_headline_invalid() {
let src = "
// Package foo does a thing.
Expand Down
6 changes: 3 additions & 3 deletions libflux/go/libflux/buildinfo.gen.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ var sourceHashes = map[string]string{
"libflux/flux-core/src/bin/fluxc.rs": "bf275289e690236988049fc0a07cf832dbac25bb5739c02135b069dcdfab4d0f",
"libflux/flux-core/src/bin/fluxdoc.rs": "bad4b12bcf4a8bc1a94cb37cda004bf7fb593abf3f0c6c3a2af6fabc60337c5d",
"libflux/flux-core/src/doc/example.rs": "6414756b3c74df1b58fdb739592e74ded3f89d85d647809333f72a3f6aad146f",
"libflux/flux-core/src/doc/mod.rs": "93c7b779078eb70bde4deabf333a714c4db2f283784880747a51a16216cdb5bd",
"libflux/flux-core/src/doc/mod.rs": "e8aae31bc4a60836d7258a03f6827b76e9fad44c889db6a21d6679c26818f2d2",
"libflux/flux-core/src/errors.rs": "5ee16ec2fd281f7c115ba0b7bcf3380749f64b7a282eb0fab7e6afe9858f3d4d",
"libflux/flux-core/src/formatter/mod.rs": "3d26f82f929e4a1f1c188b96b2a8a8c5e2a2fb8f0338fcfebaceead47cd2c4ef",
"libflux/flux-core/src/lib.rs": "443aed16dd600eecc1ffbee2d2dead6788e796cd5a278eb5dafb123843b8959e",
Expand Down Expand Up @@ -81,7 +81,7 @@ var sourceHashes = map[string]string{
"stdlib/contrib/anaisdg/statsmodels/linearreg_test.flux": "c273b5eeeb3da3b8405e6abdb82100793b6719f20755931aeaf9e343568d0dda",
"stdlib/contrib/bonitoo-io/alerta/alerta.flux": "729c6b1d714df1bf81d23e721bf3ce9176e6c18f78cf81fc25d7a6dad9b6ae79",
"stdlib/contrib/bonitoo-io/hex/hex.flux": "85e6bb6a6937274291bcd3ff4bd9802baff1c61f6dd168c6441cfd4dcd70e608",
"stdlib/contrib/bonitoo-io/servicenow/servicenow.flux": "e973b97dd238cd23c41161b22339478012e28b0947ca1adc3763a1b376eef897",
"stdlib/contrib/bonitoo-io/servicenow/servicenow.flux": "708bfd4a1e3acd96d283f098c84ea43f84528333e946097a1169255856a56383",
"stdlib/contrib/bonitoo-io/tickscript/alert_test.flux": "e3751038830c09b1bcd9bbf0c97b8cbbae78115a34e8bd9785ddec8bfb494bd6",
"stdlib/contrib/bonitoo-io/tickscript/alert_with_topic_test.flux": "f730d7f49080b2e9fae4c1e6575d65a5b49a1ef8b72d938b727e4359cd39779a",
"stdlib/contrib/bonitoo-io/tickscript/deadman_empty_test.flux": "7d0baf3fc03c950c4533ee4dd504450c46997086a7fdaede62752d7021ce26aa",
Expand All @@ -101,7 +101,7 @@ var sourceHashes = map[string]string{
"stdlib/contrib/jsternberg/rows/map_with_test.flux": "645ae1e18339a0cd70159a377cc7ac15b2f8629563b3155ef549308ac7eab4ee",
"stdlib/contrib/jsternberg/rows/rows.flux": "3bb81b01b391de76d50e41423b5987ffe9a67cd61a9618484559a0c3738b4edf",
"stdlib/contrib/rhajek/bigpanda/bigpanda.flux": "baf43d9f0d6565377bde00be7b024f952767b83239ed30a0d20c88f5522f03d6",
"stdlib/contrib/sranka/opsgenie/opsgenie.flux": "768a8393075be8b091a86eb17fc8a28c0d4b9a2b100bbabe208fa9b0a3baa0b5",
"stdlib/contrib/sranka/opsgenie/opsgenie.flux": "e4dfa9acbd0b6ad0ea9c3a36a0878d859a49b47d1b6fec6d88be34f49fa58d14",
"stdlib/contrib/sranka/sensu/sensu.flux": "bd9c2513b70d5f9d4dde93b453c384557220595ad9ce4b219ab997d3c849ce55",
"stdlib/contrib/sranka/teams/teams.flux": "758b16ed2361e2d869ab5c1c553c0ab00e629611eb0cbc7ab7884675f7b90404",
"stdlib/contrib/sranka/telegram/telegram.flux": "18186ef3da9c35cb15cc30dd78cabc60eb6381f85857d9c3d631c3214bb6f314",
Expand Down
3 changes: 2 additions & 1 deletion stdlib/contrib/bonitoo-io/servicenow/servicenow.flux
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ import "json"
// - password: ServiceNow password to use for HTTP BASIC authentication.
// - description: Event description.
// - severity: Severity of the event.
//
// Supported values:
// - `critical`
// - `major`
Expand Down Expand Up @@ -219,4 +220,4 @@ endpoint = (url, username, password, source="Flux") =>
),
}
},
)
)
3 changes: 2 additions & 1 deletion stdlib/contrib/sranka/opsgenie/opsgenie.flux
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ builtin respondersToJSON : (v: [string]) => string
// Defaults to [message](https://docs.influxdata.com/flux/v0.x/stdlib/contrib/sranka/opsgenie/sendalert/#message).
// - description: Alert description. 15000 characters or less.
// - priority: Opsgenie alert priority.
//
// Valid values include:
// - `P1`
// - `P2`
Expand Down Expand Up @@ -200,4 +201,4 @@ endpoint = (url="https://api.opsgenie.com/v2/alerts", apiKey, entity="") =>
),
}
},
)
)

0 comments on commit 0ebd453

Please sign in to comment.