So me and Iambian have been working on projects and one of our biggest issues has been keeping everything even remotely documented.

So I whipped up this python script to parse specially formatted comments and spit out a text file containing all the information in a slightly organized fashion. In an attempt to force us to at least put some kind of documentation down.

Also supports Spitting out a to do file.

I plan on making it support some kinda HTML output at some point. But I have yet to figure out how I want to do that. (CHMs would be nice but google failed me Sad)

Python Script :
https://bitbucket.org/Geekboy1011/pythonz80doc
Sounds very handy, I think I remember Timendus(?) coming up with something similar. You would put info before your routines and it would spit out a HTML file with it organised.
Thats pretty much the plan and I remember someone working on something similar before. I just have to figure out how to do the html stuff Very Happy
I came up with a system based on Spasm macros:

Code:

#ifdef REGENERATE_DOCUMENTATION
#macro documentSection(text)
   .echo >>   microsRoutines.txt   "\n\n================================================================================\n"
   .echo >>   microsRoutines.txt   "======= ", text, " =======\n"
   .echo >>   microsRoutines.txt   "================================================================================\n"
#endmacro
#macro documentRoutine(text)
   .echo >>   microsRoutines.txt   "\n------- ", text, " -------\n"
#endmacro
#macro document(text)
   .echo >>   microsRoutines.txt   text, "\n"
#endmacro
; This regex replaces comments with document()
; Find: \r\n; ([^(\r\n)]+)   Replace: \r\ndocument\("$1"\)
; This regex replaces labels followed by document() with the label and documentRoutine()
; Find: \r\n(\w*):\r\ndocument\(   Replace: \r\n$1:\r\ndocumentRoutine\("$1"\)\r\ndocument\(
; Reset document.
.echo >   microsRoutines.txt   "MICROS SYSTEM ROUTINES DOCUMENTATION\n"
#else
#macro documentSection(text)
   ; Do nothing.
#endmacro
#macro documentRoutine(text)
   ; Do nothing.
#endmacro
#macro document(text)
   ; Do nothing.
#endmacro
#endif

.
.
.

documentSection("KEYBOARD")
document("It might be nice to have a GetString routine at some point.  Whatever.")

;------ GetAscii ---------------------------------------------------------------
GetAscii:
documentRoutine("GetAscii")
document("Gets a single key press, with modifiers from shiftFlags processed.  2nd and")
document("Alpha flags are reset, unless alpha-lock is enabled, in which case only 2nd is")
document("reset.")
document("Inputs:")
document(" - inputerFlags")
document("Outputs:")
document(" - ASCII char in B, might be a control char")
document(" - D: Shift flags")
document(" - E: inputerFlags")
document("Destroys:")
document(" - Pretty much everything, most likely.")


Output:

Code:

================================================================================
======= KEYBOARD =======
================================================================================
It might be nice to have a GetString routine at some point.  Whatever.

------- GetAscii -------
Gets a single key press, with modifiers from shiftFlags processed.  2nd and
Alpha flags are reset, unless alpha-lock is enabled, in which case only 2nd is
reset.
Inputs:
 - inputerFlags
Outputs:
 - ASCII char in B, might be a control char
 - D: Shift flags
 - E: inputerFlags
Destroys:
 - Pretty much everything, most likely.
I actually went to move that exact stuff over to brass and well brass doesn't support writing data out to files Sad hence why I wrote this Smile

So that was pretty much inspiration Razz
tr1p1ea wrote:
Sounds very handy, I think I remember Timendus(?) coming up with something similar. You would put info before your routines and it would spit out a HTML file with it organised.


Timendus and I both have versions of this that we implemented for Vera. His was more comprehensive, but mine is available here: http://sfgp.cemetech.net/?page=z80asmdoc
The link for yours leads to a 404 on my system Sad
And yeah I saw that and decided I still wanted my own Razz but that's just be being picky
Huh, apparently I deleted the source from my site at some point, I'll have to re-upload that =(
  
Register to Join the Conversation
Have your own thoughts to add to this or any other topic? Want to ask a question, offer a suggestion, share your own programs and projects, upload a file to the file archives, get help with calculator and computer programming, or simply chat with like-minded coders and tech and calculator enthusiasts via the site-wide AJAX SAX widget? Registration for a free Cemetech account only takes a minute.

» Go to Registration page
Page 1 of 1
» All times are UTC - 5 Hours
 
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum

 

Advertisement