improve comment in tools::Long header

Change-Id: I1130dc1f30caf1b4d5c51dd39e159672411d4abd
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/105933
Tested-by: Jenkins
Reviewed-by: Noel Grandin <noel.grandin@collabora.co.uk>

1 files changed, 9 insertions, 6 deletions

diff --git a/include/tools/long.hxx b/include/tools/long.hxx
index ef707070af8b..5e0800f2c274 100644
--- a/include/tools/long.hxx
+++ b/include/tools/long.hxx
@@ -13,13 +13,16 @@
 /**
  * We have an unfortunate problem in that, on Windows (both 32 and 64-bit), long is always 32-bit.
  * But on Linux (64-bit) long is 64-bit. Which leads to nasty situations where things that work
- * on Linux, fail on Windows.
+ * on Linux, failed on Windows.
  * So.....,
- * (1) introduce a typedef that will replace all usage of long in our codebase.
- * (2) to start with, that typedef acts that same as the long it replaces
- * (3) once the replacement is complete, this typedef will, on windows, become 64-bit.
- * (4) and once the fallout from (3) is fixed, we can start replacing tools::Long with things
- *     like sal_Int64.
+ * (1) introduce a typedef that replaces (almost) all previous usage
+ * (2) on 64-bit Windows, this typedef is forced to 64-bit (32-bit platforms, including 32-bit Windows, are left alone)
+ * (3) fix fallout from (2)
+ *
+ * As a consequence of the above, it would be best, over the long term, to regard usage
+ * of tools::Long in the codebase as meaning "we're not sure what the ideal size of the datatype is",
+ * and where possible, replace it with a better datatype like sal_Int32/sal_Int64/etc.
+ *
  */
 namespace tools
 {