The file 'sparse.txt' contains some explanation about the
differences between the attributes 'nocast' and 'bitwise'.
It's valuable information.
So convert it to markdown syntax and rename it to a more
self-explanatory name.
Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx>
---
Documentation/index.rst | 7 ++++++
Documentation/nocast-vs-bitwise.md | 41 ++++++++++++++++++++++++++++++++++
Documentation/sparse.txt | 45 --------------------------------------
3 files changed, 48 insertions(+), 45 deletions(-)
create mode 100644 Documentation/nocast-vs-bitwise.md
delete mode 100644 Documentation/sparse.txt
diff --git a/Documentation/index.rst b/Documentation/index.rst
index f68bb42f2..d5aa0c5bf 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -6,6 +6,13 @@ Welcome to sparse's documentation
.. toctree::
:maxdepth: 1
+User documentation
+------------------
+.. toctree::
+ :maxdepth: 1
+
+ nocast-vs-bitwise
+
Developer documentation
-----------------------
.. toctree::
diff --git a/Documentation/nocast-vs-bitwise.md b/Documentation/nocast-vs-bitwise.md
new file mode 100644
index 000000000..b649abcd5
--- /dev/null
+++ b/Documentation/nocast-vs-bitwise.md
@@ -0,0 +1,41 @@
+# __nocast vs __bitwise
+
+`__nocast` warns about explicit or implicit casting to different types.
+HOWEVER, it doesn't consider two 32-bit integers to be different
+types, so a `__nocast int` type may be returned as a regular `int`
+type and then the `__nocast` is lost.
+
+So `__nocast` on integer types is usually not that powerful. It just
+gets lost too easily. It's more useful for things like pointers. It
+also doesn't warn about the mixing: you can add integers to `__nocast`
+integer types, and it's not really considered anything wrong.
+
+`__bitwise` ends up being a *stronger integer separation*. That one
+doesn't allow you to mix with non-bitwise integers, so now it's much
+harder to lose the type by mistake.
+
+So the basic rule is:
+
+ - `__nocast` on its own tends to be more useful for *big* integers
+that still need to act like integers, but you want to make it much
+less likely that they get truncated by mistake. So a 64-bit integer
+that you don't want to mistakenly/silently be returned as `int`, for
+example. But they mix well with random integer types, so you can add
+to them etc without using anything special. However, that mixing also
+means that the `__nocast` really gets lost fairly easily.
+
+ - `__bitwise` is for *unique types* that cannot be mixed with other
+types, and that you'd never want to just use as a random integer (the
+integer `0` is special, though, and gets silently accepted - it's
+kind of like `NULL` for pointers). So `gfp_t` or the `safe endianness`
+types would be `__bitwise`: you can only operate on them by doing
+specific operations that know about *that* particular type.
+
+Generally, you want `__bitwise` if you are looking for type safety.
+`__nocast` really is pretty weak.
+
+## Reference:
+
+* Linus' e-mail about `__nocast` vs `__bitwise`:
+
+ <https://marc.info/?l=linux-mm&m=133245421127324&w=2>
diff --git a/Documentation/sparse.txt b/Documentation/sparse.txt
deleted file mode 100644
index 383376c04..000000000
--- a/Documentation/sparse.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-Sparse
-~~~~~~
-
-__nocast vs __bitwise:
-
-__nocast warns about explicit or implicit casting to different types.
-
-HOWEVER, it doesn't consider two 32-bit integers to be different
-types, so a __nocast 'int' type may be returned as a regular 'int'
-type and then the __nocast is lost.
-
-So "__nocast" on integer types is usually not that powerful. It just
-gets lost too easily. It's more useful for things like pointers. It
-also doesn't warn about the mixing: you can add integers to __nocast
-integer types, and it's not really considered anything wrong.
-
-__bitwise ends up being a "stronger integer separation". That one
-doesn't allow you to mix with non-bitwise integers, so now it's much
-harder to lose the type by mistake.
-
-So the basic rule is:
-
- - "__nocast" on its own tends to be more useful for *big* integers
-that still need to act like integers, but you want to make it much
-less likely that they get truncated by mistake. So a 64-bit integer
-that you don't want to mistakenly/silently be returned as "int", for
-example. But they mix well with random integer types, so you can add
-to them etc without using anything special. However, that mixing also
-means that the __nocast really gets lost fairly easily.
-
- - "__bitwise" is for *unique types* that cannot be mixed with other
-types, and that you'd never want to just use as a random integer (the
-integer 0 is special, though, and gets silently accepted iirc - it's
-kind of like "NULL" for pointers). So "gfp_t" or the "safe endianness"
-types would be __bitwise: you can only operate on them by doing
-specific operations that know about *that* particular type.
-
-Generally, you want __bitwise if you are looking for type safety.
-"__nocast" really is pretty weak.
-
-Reference:
-
-* Linus' e-mail about __nocast vs __bitwise:
-
- http://marc.info/?l=linux-mm&m=133245421127324&w=2
--
2.16.0
--
To unsubscribe from this list: send the line "unsubscribe linux-sparse" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
