Saturday, November 21, 2026

Document Generating Comments

Some of my projects start off as "I wish there was a a fully Vim-style XYZ...". So I reach out to my AI buddy and start helping him code such a thing for me. A couple of times the project ended up being REALLY cool. So I need to be able to work with the code. Ideally completely taking it over myself. However these are usually pretty ambitious projects so I need to do some learning - which is great!

To aid in this I thought about utilizing an existing 'code comments to documentation' solutions that are out there... BUT!

I have a stand alone HTML treeview driven notes app I built! And in looking at some of the solutions out there I feel like the comments are a lot. I don't want to spam my code with a crap ton of comments, just to get documentation. I have to be able to read the code.

So I put together a Python script and my own comment syntax for a few things (only tested against C++ so far, it it should be able to do other languages via config files). I've used it on the C++ app version of the stand alone HTML notes app and it worked amazingly well! It makes tracking down specific code etc much easier.

Some of its most exciting features:

Print Actual Code
Using
//>>
...
//<<
You can have the code between those written to the docs. So there's no maintaining those code snippets - they ARE the code.

/*
...
!_method
...
*/
This documents a method's footprint - inputs, output, etc -- AND where that method is called in other areas of the code!

/*
...
!_ctor
...
*/
This is like the method one but for constructors.

You can do custom entries in the help system and more. It does increase the amount of comments of course but - in using indent based folding in Vim - I find them fairly unobtrusive! In the future I'll develop this tool further and provide a link to the repo.

No comments:

Post a Comment

Project Structure Documentation Key

 I've added a 'key' to the documentation from comments Python script: structure So: //!_structure=/Project Structure Generates t...