lix-project/lix
20
57
Fork 31
Code Issues 347 Code Review (Gerrit) Projects 3 Releases Wiki Activity

lix-doc: don't chomp bold headings off

Browse source 
There are a few places in nixpkgs lib where `**Foo**:` is used as a heading instead of the usual markdown `# Foo` ones. I think this is intentional with how it gets rendered in the manual, e.g. [`lib.lists.sortOn`][1].

[1]: https://nixos.org/manual/nixpkgs/stable/#function-library-lib.lists.sortOn

`nix-doc` prints this as
```
   *Laws**:
       ```nix
       sortOn f == sort (p: q: f p < f q)
       ```
```
chomping off the first asterisk as part of `cleanup_single_line` that's meant to deal with `/** \n * \n * \n */` style doc comments. This also means the usage in lix ends up funny-looking with a trailing asterisk as if there's a footnote to pay attention to (which is how I first noticed it, heh)

The fix:

When cleaning up a single line and removing a prefix comment character,
ensure it's followed by whitespace (or the last character of the line).

Upstream-PR: https://github.com/lf-/nix-doc/pull/26
Change-Id: If2870c53a632f6bbbcca98a4bfbd72f5bef37879
This commit is contained in:
FireFly 2024-05-15 15:24:03 -07:00 committed by Jade Lovelace
parent 03655c310d
commit eca8bce081
1 changed files with 18 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
lix-doc/src/lib.rs
View file

@ -84,9 +84,13 @@ fn indented(s: &str, indent: usize) -> String {
/// Cleans up a single line, erasing prefix single line comments but preserving indentation /// Cleans up a single line, erasing prefix single line comments but preserving indentation
fn cleanup_single_line<'a>(s: &'a str) -> &'a str { fn cleanup_single_line<'a>(s: &'a str) -> &'a str {
let mut cmt_new_start = 0; let mut cmt_new_start = 0;
for (idx, ch) in s.char_indices() { let mut iter = s.char_indices().peekable();
while let Some((idx, ch)) = iter.next() {
// peek at the next character, with an explicit '\n' as "next character" at end of line
let (_, next_ch) = iter.peek().unwrap_or(&(0, '\n'));
// if we find a character, save the byte position after it as our new string start // if we find a character, save the byte position after it as our new string start
if ch == '#' || ch == '*' { if ch == '#' || (ch == '*' && next_ch.is_whitespace()) {
cmt_new_start = idx + 1; cmt_new_start = idx + 1;
break; break;
} }
@ -206,7 +210,7 @@ fn visit_lambda(name: String, lambda: &Lambda) -> SearchResult {
SearchResult { SearchResult {
identifier: name, identifier: name,
doc: comment, doc: comment,
param_block param_block,
} }
} }
@ -246,7 +250,7 @@ pub extern "C" fn nd_get_function_docs(
filename: *const c_char, filename: *const c_char,
line: usize, line: usize,
col: usize, col: usize,
) -> *const c_char { ) -> *const c_char {
let fname = unsafe { CStr::from_ptr(filename) }; let fname = unsafe { CStr::from_ptr(filename) };
fname fname
.to_str() .to_str()
@ -257,9 +261,9 @@ pub extern "C" fn nd_get_function_docs(
eprintln!("panic!! {:#?}", e); eprintln!("panic!! {:#?}", e);
e e
}) })
.ok() .ok()
}) })
.flatten() .flatten()
.and_then(|s| CString::new(s).ok()) .and_then(|s| CString::new(s).ok())
.map(|s| s.into_raw() as *const c_char) .map(|s| s.into_raw() as *const c_char)
.unwrap_or(ptr::null()) .unwrap_or(ptr::null())
@ -319,8 +323,16 @@ mod tests {
let ex1 = " * a"; let ex1 = " * a";
let ex2 = " # a"; let ex2 = " # a";
let ex3 = " a"; let ex3 = " a";
let ex4 = " *";
assert_eq!(cleanup_single_line(ex1), " a"); assert_eq!(cleanup_single_line(ex1), " a");
assert_eq!(cleanup_single_line(ex2), " a"); assert_eq!(cleanup_single_line(ex2), " a");
assert_eq!(cleanup_single_line(ex3), ex3); assert_eq!(cleanup_single_line(ex3), ex3);
assert_eq!(cleanup_single_line(ex4), "");
}
#[test]
fn test_single_line_retains_bold_headings() {
let ex1 = " **Foo**:";
assert_eq!(cleanup_single_line(ex1), ex1);
} }
} }