Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Code samples that actually compile - Clare Macrae

3 views

Published on

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.

Published in: Software
  • Be the first to comment

  • Be the first to like this

Code samples that actually compile - Clare Macrae

  1. 1. 1 Code Samples that Actually Compile Clare Macrae She/Her
  2. 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. 3 Easy – I’ll copy the sample code from the docs, and build that!
  4. 4. 4
  5. 5. 5
  6. 6. 6 Now what?
  7. 7. 7 Sounds Familiar?
  8. 8. 8 Now what? Search for missing symbol in docs – No...
  9. 9. 9 Now what? Search for missing symbol in docs – No... Search the whole repo for similar code
  10. 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. 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. 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. 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. 14 A Better Way…
  15. 15. 15 Class.tests.cpp
  16. 16. 16 Class.tests.cpp
  17. 17. 17 test-fixtures.source.md
  18. 18. 18 Console window
  19. 19. 19 On github: test-fixtures.md
  20. 20. 20 On github: test-fixtures.md
  21. 21. 21 On github: test-fixtures.md
  22. 22. 22 https://github.../Class.tests.cpp#L94-L103
  23. 23. 23 What’s going on here? .source.md snippet: name
  24. 24. 24 // begin-snippet: name … // end-snippet What’s going on here? .source.md snippet: name source file(s)
  25. 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. 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. 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. 28 Guaranteed-working code samples mdsnippets.com … and a way to see their context. Thanks to @SimonCropp for this excellent tool!

×