Don't let clang-format reorder Fiddle `#include`s (#7887)

The documentation added by #6844 included instructions to make sure that
the Fiddle `#include` in a file comes after all the other `#include`s,
but it's easy to accidentally violate this via `clang-format`, as
happened for `source/slang/slang-ast-modifier.h` in #7559. This PR
guards against this sort of violation by separating all Fiddle
`#include`s from other `#include`s via a blank line followed by a `//`
line (as we already do in most cases), and also adds a sentence about
this in `tools/slang-fiddle/README.md`.

As a bonus, I also enabled Markdown syntax highlighting for all the code
blocks in that doc file.

Co-authored-by: Ellie Hermaszewska <ellieh@nvidia.com>

1 files changed, 12 insertions, 4 deletions

diff --git a/tools/slang-fiddle/README.md b/tools/slang-fiddle/README.md
index 2ae57c8e3..0ccb64075 100644
--- a/tools/slang-fiddle/README.md
+++ b/tools/slang-fiddle/README.md
@@ -9,7 +9,7 @@ Invoking Fiddle
 
 Fiddle gets invoked from the command line with a command line like:
 
-```
+```sh
 slang-fiddle -i source/ -o generated/ a.cpp b.h c.h d.cpp ...
 ```
 
@@ -51,7 +51,7 @@ During the scraping step, Fiddle will run the Slang lexer on each of the input f
 
 Putting `FIDDLE()` in front of an ordinary C++ `class`, `struct`, or `namespace` declaration tells Fiddle that it should include that C++ construct in the model of the program that it scrapes. For example, given this input:
 
-```
+```cpp
 FIDDLE()
 namespace MyProgram
 {
@@ -68,7 +68,7 @@ Fiddle will include the `MyProgram` namespace and the `MyProgram::A` type in its
 
 A programmer can place Fiddle-specific modifiers inside the `FIDDLE()` invocation before a type, to apply those modifiers to the model of that type:
 
-```
+```cpp
 FIDDLE(abstract)
 class Thing { /* ... */ };
 
@@ -78,7 +78,7 @@ class ConcreteThing : public Thing { /* ... */ }
 
 One important constraint is that any `struct` or `class` type marked with `FIDDLE()` *must* have an invocation of the form `FIDDLE(...)` (that is, `FIDDLE` applied to an actual ellipsis `...`) as the first item after the opening curly brace for its body:
 
-```
+```cpp
 FIDDLE()
 struct A
 {
@@ -98,6 +98,14 @@ Note again that Fiddle will *ignore* any fields not marked with `FIDDLE()`, so b
 In order for Fiddle to provide the macros that each `FIDDLE()` invocation expands into, any input file that includes invocations of `FIDDLE()` *must* also `#include` the corresponding generated file.
 For example, the input file `a.cpp` should `#include "a.cpp.fiddle"`.
 The `#include` of the generated output file should come *after* any other `#include`s, to make sure that any `.h` files that also use `FIDDLE()` don't cause confusion.
+Because `clang-format` automatically reorders `#include`s, you must separate this one from the others by preceding it with a blank line followed by an empty comment line:
+
+```cpp
+#include "something-else.h"
+
+//
+#include "a.cpp.fiddle"
+```
 
 Text Templates
 --------------