Tired of keeping your documentation up-to-date with your library code? Tired of users logging bus because your documentation is out of date? If you write user documentation in Markdown, you can have guaranteed-working documentation using Simon Cropp's Markdown Snippets - https://github.com/SimonCropp/MarkdownSnippets.

1. 1
Code Samples that Actually Compile
Clare Macrae
She/Her

2. 2
Recently…
• I needed to quickly try these Catch2 macros:
– TEMPLATE_TEST_CASE_METHOD_SIG
– TEMPLATE_PRODUCT_TEST_CASE_METHOD_SIG
• The docs had code samples.

3. 3
Easy – I’ll copy the
sample code from
the docs, and build
that!

4. 4

5. 5

6. 6
Now what?

7. 7
Sounds Familiar?

8. 8
Now what?
Search for missing
symbol in docs –
No...

9. 9
Now what?
Search for missing
symbol in docs –
No...
Search the whole
repo for similar code

10. 10
Now what?
Search for missing
symbol in docs –
No...
Found it – so, how
does it differ from
the code in the
docs?
Search the whole
repo for similar code

11. 11
Now what?
Search for missing
symbol in docs –
No...
Found it – so, how
does it differ from
the code in the
docs?
Paste in the relevant
missing bit…
Search the whole
repo for similar code

12. 12
Now what?
Search for missing
symbol in docs –
No...
Found it – so, how
does it differ from
the code in the
docs?
Paste in the relevant
missing bit…
Search the whole
repo for similar code
Test it – it works!

13. 13
Now what?
Search for missing
symbol in docs –
No...
Found it – so, how
does it differ from
the code in the
docs?
Paste in the relevant
missing bit…
Search the whole
repo for similar code
Test it – it works!
Fix the docs and
submit a pull
request – of course

14. 14
A Better Way…

15. 15
Class.tests.cpp

16. 16
Class.tests.cpp

17. 17
test-fixtures.source.md

18. 18
Console window

19. 19
On github: test-fixtures.md

20. 20
On github: test-fixtures.md

21. 21
On github: test-fixtures.md

22. 22
https://github.../Class.tests.cpp#L94-L103

23. 23
What’s going on here?
.source.md
snippet: name

24. 24
// begin-snippet: name
…
// end-snippet
What’s going on here?
.source.md
snippet: name
source file(s)

25. 25
// begin-snippet: name
…
// end-snippet
What’s going on here?
.source.md
snippet: name
source file(s) whole file(s)
{ }some text to insert
in to documentation,
such as a test output
file

26. 26
// begin-snippet: name
…
// end-snippet
What’s going on here?
.source.md
snippet: name
source file(s) whole file(s)
{ }
mdsnippets
some text to insert
in to documentation,
such as a test output
file

27. 27
// begin-snippet: name
…
// end-snippet
What’s going on here?
.source.md
snippet: name
source file(s) whole file(s)
{ }
mdsnippets
.md
…..
…..
…..
snippet source
Easily view
Source and
Context
some text to insert
in to documentation,
such as a test output
file

28. 28
Guaranteed-working code samples
mdsnippets.com
… and a way to see their context.
Thanks to @SimonCropp for this excellent tool!