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