Adding Node.traverse() examples and/or documentation.

[kaesluder]

I have the following example of a function using Node.traverse() to extract text as an alternative to the recursive examples from the README. If there's interest, I can clean it up and put in a PR adding it to examples or the generated API documentation.

fn extract_text_traverse<'a>(root: &'a AstNode<'a>) -> String {
    let mut output_text = String::new();

    // Use `traverse` to get an iterator of `NodeEdge` and process each.
    for edge in root.traverse() {
        if let NodeEdge::Start(node) = edge {
            // Handle the Start edge to process the node's value.
            if let NodeValue::Text(ref text) = node.data.borrow().value {
                // If the node is a text node, append its text to `output_text`.
                output_text.push_str(text);
            }
        }
    }

    output_text
}

    #[test]
    fn extract_text_traverse_test() {
        let markdown_input = "Hello, *worl[d](https://example.com/)*";
        let arena = Arena::new();
        let options = ComrakOptions::default();
        let root = parse_document(&arena, markdown_input, &options);
        assert_eq!("Hello, world", extract_text_traverse(root));
    }

It should handle nested inline markup to generate a plain text string.

[kivikakk]

Thank you so much, that'd be lovely! This is a really nice example!

[kaesluder]

Thanks. I'll do a bit of comment editing and make sure the proper use statements are included.

[kaesluder]

And, last night I found an even easier iteration method. 🤨

fn extract_text<'a>(root: &'a AstNode<'a>) -> String {
    let mut output_text = String::new();

    // Use `traverse` to get an iterator of `NodeEdge` and process each.
    for node in root.descendants() {
        if let NodeValue::Text(ref text) = node.data.borrow().value {
            // If the node is a text node, append its text to `output_text`.
            output_text.push_str(text);
        }
    }

    output_text
}

I might submit a dockstring PR because descendants() and traverse() have different signatures but nearly identical documentation text. (New at this.)

[kaesluder]

Happy to tackle any other documentation needs.

[kivikakk]

I appreciate that so much! How about the usage example in README.md? (Under "Or you can parse the input into an AST yourself, manipulate it, and then use your desired formatter:") It's extremely verbose and you've done a really good job of documenting some much nicer APIs. The iter_nodes and text replacement stuff looks really bad these days — NodeValue::Text doesn't even take a Vec<u8> anymore, so it's just totally wrong as-is!

[kaesluder]

Sounds good, it might be a few weeks until I get some bandwidth to work on it.

[kivikakk]

Yeah, of course, no worries at all :) Life's always like that. Thank you (as always) for your interest and effort! ❤️

[kaesluder]

PR submitted. Comments welcome.

[kivikakk]

Really excellent — thank you so much.