Add wrap_with method to NodeRef

[andrewbanchich]

Added a higher level method for people to use to wrap a NodeRef with a new NodeRef.

[Ygg01]

It seems ok, although a bit lite on docs or examples.

[Ygg01]

@andrewbanchich There was no need to close the request, I merely noted, it could use some more docs (truth be told, most of kuchiki needs more docs). It definitely took new a minute to figure out how and why, should this behave.

[andrewbanchich]

@Ygg01 Thanks, I agree it could use some docs.

The reason I closed this was I was adding some examples and testing them last night, but realized my PR doesn't work. I had used it in my application code as is, except I created a new trait called Wrap and implemented Wrap for NodeRef and that worked. I'm not sure why adding it directly to NodeRef in the library code isn't working though.

I think Kuchiki overall could use some more docs / examples since I don't really understand the concepts of NodeRef / NodeDataRef / NodeData etc. from the descriptions and that makes it hard for me to debug things like this.

[Ygg01]

@andrewbanchich Hm, that is weird. I'll look into it. Please don't delete this branch.

As far as Nodes are concerned, @SimonSapin is probably best to ask.

However, I'll try to partially answer it at least.

NodeData

NodeData is an enum saying which type of Node and what kind of data does it have.

pub enum NodeData {
    Element(ElementData),
    Text(RefCell<String>),
    Comment(RefCell<String>),
    ProcessingInstruction(RefCell<(String, String)>),
    Doctype(Doctype),
    Document(DocumentData),
    DocumentFragment,
}

NodeRef

Is essentially a wrapper for a node i.e. struct NodeRef<Rc<Node>>. Ok, but then what is node?

Node

Node is actually crucial, it contains both the data and links to neighboring nodes (i.e. siblings, parents, children).

pub struct Node {
    parent: Cell<Option<Weak<Node>>>,
    previous_sibling: Cell<Option<Weak<Node>>>,
    next_sibling: Cell<Option<Rc<Node>>>,
    first_child: Cell<Option<Rc<Node>>>,
    last_child: Cell<Option<Weak<Node>>>,
    data: NodeData,
}

NodeDataRef

Is wrapper a form of a strong pointer to NodeRef. Not hundred percent sure what are they used for.