Our great sponsors
-
d.awk
An Awk script to generate documentation from Markdown comments in C/C++/Java/JavaScript/C# source code.
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
If you'll indulge me for a moment, I have a story to tell:
Many years ago, I had this idea of creating a documentation tool for my hobby projects that was based on Awk.
I liked Doxygen, but it was a bit heavy duty for a small C library with only a handful of functions. You could almost guarantee that Awk would be available on the system where you might be compiling the project, so you could just bundle the awk script with your sources, add two lines to your makefile and have HTML documentation ready to go.
Now I had never heard of Markdown at this time; It was before StackOverflow or GitHub was a thing (perhaps they existed, but I haven't used them yet). Therefore my syntax was a crude markup scheme that was difficult to explain and didn't always work correctly.
Skip forward a couple of years and I had the bright idea to rewrite the script to rather use a Markdown syntax. This ended up being one of those hobby projects that you never really finish, and it grew organically to include all sorts of Markdown features. The result of that effort is now on GitHub [1].
Where does Markdeep fit into all of this? Sometimes when I stumble upon a project on GitHub that I find interesting, I click on the author's name to see what other repositories they have that looks interesting. One day I browsed GitHub like that and stumbled upon user r-lyeh's `stddoc.c` file [2].
It is a C program that simply extracts the comments from your source file and appends the Markdeep tags to the end. If you save the result to a HTML file, you achieve the same result as my script, except the implementation is much much simpler.
I nearly fell off my chair when I realised that all the effort I put into my own script was basically made useless(*) by Markdeep. Instead of parsing the markdown, I could rather have had Markdeep do all the heavy lifting, and it comes with a bunch of very nice features that I doubt I'd ever be able to implement in my own script.
[1]: https://github.com/wernsey/d.awk