documentation inconsistencies about mutability

[dherman]

Since commit fd419de, the docs have become inconsistent about whether LazyCell allows mutation. There are several places that claim it's permanently frozen once it's been initialized:

This crate provides a LazyCell struct which acts as a lazily filled Cell, but with frozen contents.

LazyCell: A lazily filled Cell, with frozen contents.

But with that commit, the borrow_mut method now allows it to be mutated, so it doesn't really make sense to describe it as having frozen contents anymore, does it?

That commit also resulted in this pretty confusing sentence:

The limitation of a LazyCell is that after it is initialized and shared, it can be modified.

I can't really figure out what that's trying to say. What does sharing have to do with it, and how is it a limitation to be able to modified?

[dherman]

/cc @matklad

[matklad]

I can't really figure out what that's trying to say. What does sharing have to do with it, and how is it a limitation to be able to modified?

Yeah, that's definitely confusing :) I think the best way to actually document this is to use the original formulation of completely frozen, once filled, which is like 99% correct and what you want most of the time.

The trick with borrow_mut is that, if you have &mut access to LazyCell, it actually acts more or less Option<T>, and you can do whatever you like with it. However, if you only have & access, then it has this peculiar semantics of transitioning from None to Some(value) once and then staying at the value.

[indiv0]

Yeah the documentation is definitely confusing at the moment. I think matklad's suggested wording would be a good substitute, but I'm not sure how to accurately describe the &mut vs & mut difference in a clear way in the documentation. Thoughts?

[indiv0]

I decided to add a separate commit (9d634d1) documenting the LazyCell::borrow_mut mutability edge-case.