improve docs

Author: timotheecour

changelog.md

@@ -126,7 +126,12 @@
   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
 --------------