Update capabilities.md #102
Conversation
Added a lost parenthesis and added clarity on the << symbol. Signed-off-by: Craig Christianson <[email protected]>
| @@ -96,9 +96,9 @@ By convention the 0th CSlot is kept empty, for the same reasons as keeping NULL | |||
| process virtual address spaces: to avoid errors when uninitialised slots are used unintentionally. | |||
|
|
|||
| The field `info->CNodeSizeBits` gives a measure of the size of the initial | |||
| CNode: it will have `1 << CNodeSizeBits` CSlots. A CSlot has | |||
| CNode: it will have `1 << CNodeSizeBits` CSlots where the `<<` symbol represents the left bit shift operator. A CSlot has | |||
There was a problem hiding this comment.
Maybe we could drop the shift and say instead:
| CNode: it will have `1 << CNodeSizeBits` CSlots where the `<<` symbol represents the left bit shift operator. A CSlot has | |
| CNode: it will have `2 ^ CNodeSizeBits` CSlots |
There was a problem hiding this comment.
I think the 2^N notation is more clear, but there are a lot of places in the tutorials where the 1u << N notation is used that should probably be changed for consistency. It also may be used in code examples, but so far it looks like the code examples favor the BIT( ) macro. I think it is safe to assume that the reader is familiar with C notation. The only reason I added it was to ensure that the symbol is not confused with the "much less than" meaning of the << symbol. I think either way would work, and I don't really have a preference. I just think the notation should be consistent. What are your thoughts?
There was a problem hiding this comment.
In the context of that sentence << as "much less than" doesn't really make sense, so while there can be initial confusion, it should clear up eventually. I do agree that it'd be nicer not to cause any initial confusion either, though.
Overall 2^n either with super script or with ^ does seem nicer to me, at least for mathematically minded people. I think the 1 << _ notation is used to be consistent with the code. Since it's a tutorial and is trying not to introduce everything at once, the BIT macro is not used there yet and I don't think it's the place to introduce it.
If we want do 2^n instead of 1 << _ in the text, we should really review all of the tutorials an stay consistent. We should also check if that leads to strangeness in other parts of the tutorials (probably fine, though).
There was a problem hiding this comment.
(of course ^ is the xor operator, so I'm sure 2^n will also be confusing to someone out there)
|
My understanding is that the |
|
Sounds good. I'll take another look at it. I'll convert this to draft for now. |
Changed 1>>N notation to 2^N notation
|
Here is what it looks like with the superscript. Initially, it seemed less readable to me, so I added some text for clarity. |
Added a lost parenthesis and added clarity on the << symbol.