improve docs

Author: timotheecour

changelog.md

@@ -120,13 +120,18 @@
   avoid recompiling when sources don't change. This is now the preferred way to
   run tests, avoiding the usual pain of clobbering your repo with binaries or
   using tricky gitignore rules on posix. Example:
-  ```nim
+  ```bash
   nim r compiler/nim.nim --help # only compiled the first time
-  echo 'import os; echo getCurrentCompilerExe()' | nim r - # this works too
+  echo "import os; echo getCurrentCompilerExe()" | nim r - # this works too
   nim r compiler/nim.nim --fullhelp # no recompilation
   nim r --nimcache:/tmp main # binary saved to /tmp/main
   ```
-- `incompleteStruct` is now deprecated, use `completeStruct` instead.
+- a new pragma `completeStruct` for importc objects indicates the type is fully
+  specified in the nim declaration (including field ordering), and allows
+  `sizeof, alignof, offsetof` to be used at compile time, see
+  manual.html#implementation-specific-pragmas-completestruct-pragma.
+- `incompleteStruct` is now deprecated, see
+  manual.html#implementation-specific-pragmas-incompletestruct-pragma.
 
 ## Tool changes
 

compiler/pragmas.nim

@@ -872,7 +872,7 @@ proc singlePragma(c: PContext, sym: PSym, n: PNode, i: var int,
         noVal(c, it)
         incl(sym.flags, {sfThread, sfGlobal})
       of wDeadCodeElimUnused: deprecatedPragma(wDeadCodeElimUnused, "dead code elim always on")
-      of wIncompleteStruct: deprecatedPragma(wIncompleteStruct, "see '$1' instead" % wCompleteStruct.canonPragmaSpelling)
+      of wIncompleteStruct: deprecatedPragma(wIncompleteStruct, "see https://nim-lang.github.io/Nim/manual.html#implementation-specific-pragmas-incompletestruct-pragma")
       of wNoForward: pragmaNoForward(c, it)
       of wReorder: pragmaNoForward(c, it, flag = sfReorder)
       of wMagic: processMagic(c, it, sym)

doc/manual.rst

@@ -6432,8 +6432,17 @@ at least `sizeof` is correct.
       x2* {.importc: "_x2"}: pointer # renamed field
 
 See `additional examples <https://github.com/nim-lang/Nim/blob/devel/tests/misc/msizeof5.nim>`_.
-The `incompleteStruct` pragma is now deprecated as it was implying the wrong
-default.
+
+
+IncompleteStruct pragma
+-----------------------
+**deprecated**
+This was used for forwarded C declarations such as `DIR` on some platforms,
+but led to incorrect typeinfo (eg with `dumpNumberOfInstances`). Instead we
+simply avoid referring to such type by value on platforms where it's a forwarded
+declaration and only use it via pointer. Any disallowed use-by-value leads to a
+C codegen error, and we avoid silently wrong results for cases where
+use-by-value is allowed.
 
 Compile pragma
 --------------