Ok, here is my draft, and attempt to explain it.

I've given the source doc extracter the work name "harsyra" (Oxalis Acetosella,
an eatable herb), i've got some idea of a name for it but there is time for naming later. 

The comments that harsyra will be looking for is thos that begins with:
;<<*
What follows after is/should be ignored thus a valid line could look like one of these:
;<<*----------------------------------------------------------------
;<<***********************************************
;<<*.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.oOo.
(I have made the line with vary on purpose)
Every start comment ***must*** be ended with an end comment, which beings with:
;>>*
it follow the same rule as the star comment, any thing after ";>>*" is ignored.

The recomended start/end line is shown below, it's in total 78 chars long.
;<<**************************************************************************
;>>**************************************************************************

The "general format" of the comment block is this (explanation bellow)
;<<*[ignored text]
; Name: <Name of Proc>
; Description: <description>
; Arguments:
;  register: explanation.
;  "stack passed argument" - explanation.
; Returns:
;  eax: the return value.
;>>*[ignored text]

Note the space after the ":" is either assumed to needed to be there, forgetting
it may cause "undefined" behaviour/output.

The "Name field" is the name of the procedure, if this is omitted then the line
after the end comment line is assumed to be a "proc name,..." or "name:".
The name field is a one line comment, i.e. it's a string starting after "Name: "
terminated by CR(LF).

The description field contains the description, it may contain multiple lines,
the description ends when either:
"Arguments: ", "Returns: " or the "end comment line dword" (";>>*")  is encountered
The text in here is planed to be displayed with an monospaced font, thus tables,
ASCII images, etc could be put here as illustration if needed.

The Arguments field is special, it may contain two types of lines, described below,
and end when either:
"Returns: " or the "end comment line dword" (";>>*")  is encountered.
The two types of lines are registers and stack passed arguments.
 Registers:
  represeented in this form: "reg:" + description.
     Here is how an valid register argument list may look like:
   ; Arguments:
   ;  eax: Argument 0
   ;  ebx: This
   ;  ecx: that
   ;  esi: foo bar pointer
 Stack passed arguments:
  representated in this form. "arg_name - " + description.
  Here is how an valid stack passed argument list may look like:
   ; Arguments:
   ;  lpSrc - Source ptr.
   ;  lpDest - destination ptr.
   ;  strOp - String operation to performe

The Returns field may contain either the same register representation as arguments,
or if the first field isn't a "reg:" then it's assumed to be a plain text field.
When the return is a flag, then I have this suggestion:
; CF=0: CF is zero when, ...
; CF=1: this and that
thus: "flag" + "=" + 1 || 0 + ": " + description. Ideas on this? I'm not sure if
the two letter name or the full name of the flag is to be used, for now use the
"plain text" return description.
Like the description filed, it's contents is (intended) to be displayed with a
monospace font.

One last detail, the "Description", "Arguments" and "Returns" field may contain
the string "Nothing." if the field is to be considered empty. Se examples to see
how it may be used.

I hope I managed to describe the comment block, if not just ask me for a clarification.
Below is a few examples of how the comment block might look.
    

;<<******************************************************
; Name: FASM dynamic string library.
; Description:
; (c)2003 John Found
;
; You can use and modify this library, as long as modifyed
; versions are clearly marked (author of the modification
; and what is changed), copyright notice is not
; removed and the library remains free.
; Copyright for the library concept and parts written by
; me, remains to me, John Found
; Copyright for the modifyed/new parts remains to their
; authors.
;>>******************************************************
; Versions:
;   dd.mm.yyyy  version   author of modification
;     - description
;--------------------------------------------------------
;   09.07.2003  v1.0    John Found
;     - the first public version.
;   15.07.2003  v1.0.1  John Found
;     - minor bug with string table expand. Look in NewStr
;
;********************************************************


;--< How to use it >-----------------------------------------------------------------
; 1. Include "strutils.inc" somewhere in the begining of main file.
; 2. Define structure "StrTable" of type "TStrTable" somewhere in data section.
; 3. Before using of library functions, call "InitStrings"
; 4. After last use of the library (probably on close of application),
;    call "FreeStrings" to free all used memory.
; 5. Some functions are with register parameter passing, other with "stdcall"
;    parameter passing. Read the header descriptions of the functions.
;------------------------------------------------------------------------------------

; < Library functions >

;<<**********************************************************************************
; Name: InitStrings
; Description: Allocates memory for string table and allocates memory for strings.
; Start it before any work with strings.
; Arguments: Nothing.
; Returns: 0 if failed to allocate needed memory.
;>>**********************************************************************************

;<<************************************************************************************
; Name: StrPtr
; Descripton: Returns the pointer in memory of the str handle eax
; Arguments:
;  eax: handle or pointer of the string.
; Returns:
;  eax: pointer to the string buffer or NULL if error
;>>************************************************************************************

;>>************************************************************************
; Name: DelStr
; Description: Deletes the string if it is possible.
; Argumets:
;  eax: handle or pointer of the string created using NewStr.
; Returns:
;  Nothing.
;<<************************************************************************


;<<*****************************************************************************
; Name: GetControlText
; Description:
; Get the text of the [Control] using WM_GETTEXT and put it to the string with
; handle (only) in [string].
;
; if [string] = NULL creates new string and returns the handle.
; if [string] <> NULL just copyes the text.
; Arguments:
;  Control - control to aquire text from
;  string - se description field for more info.
; Returns: Nothing.
;>>*****************************************************************************
Note: "Nothing." to show it's usage.

;<<**********************************************************
; Name: SetString
; Description: Creates string and assigns it to variable. If variable
;  already contains string handle, the old string will be
;  deleted.
; Arguments:
;   ptrHString - pointer to variable containing string handle.
;   ptrSource - pointer to the source for string.
;>>**********************************************************
IMO it's better to write the [ptrHString] as above.

;<<********************************************************************************
; Name: NumToStr
; Description: NumToStr converts the number in eax to the string in any radix approx. [2..26]
; There is no parameter check, so be careful.
; Arguments:
;  edi: pointer to the string buffer
;  ecx: radix
;  eax: number to convert.
; Returns: ?
;>>********************************************************************************
    

Name: FASM dynamic string library.
Description:
 (c)2003 John Found

 You can use and modify this library, as long as modifyed
 versions are clearly marked (author of the modification
 and what is changed), copyright notice is not
 removed and the library remains free.
 Copyright for the library concept and parts written by
 me, remains to me, John Found
 Copyright for the modifyed/new parts remains to their
 authors.
----------------------------------------------------------------------------------
Name: InitStrings
Description:
Allocates memory for string table and allocates memory for strings.
Start it before any work with strings.
Arguments: Nothing.
Returns: 0 if failed to allocate needed memory.
----------------------------------------------------------------------------------
Name: StrPtr
Descripton:
Returns the pointer in memory of the str handle eax

Arguments:
 eax: handle or pointer of the string.

Returns:
 eax: pointer to the string buffer or NULL if error
----------------------------------------------------------------------------------
Name: DelStr
Description:
Deletes the string if it is possible.

Argumets:
 eax: handle or pointer of the string created using NewStr.

Returns:
 Nothing.
----------------------------------------------------------------------------------
Name: GetControlText
Description:
Get the text of the [Control] using WM_GETTEXT and put it to the string with
handle (only) in [string].

if [string] = NULL creates new string and returns the handle.
if [string] <> NULL just copyes the text.

Arguments:
 Control - control to aquire text from
 string  - se description field for more info.
----------------------------------------------------------------------------------
Name: SetString
Description:
Creates string and assigns it to variable. If variable
already contains string handle, the old string will be
deleted.

Arguments:
  ptrHString - pointer to variable containing string handle.
  ptrSource  - pointer to the source for string.
----------------------------------------------------------------------------------
Name: NumToStr
Description:
NumToStr converts the number in eax to the string in any radix approx. [2..26]
There is no parameter check, so be careful.

Arguments:
 edi: pointer to the string buffer
 ecx: radix
 eax: number to convert.

Returns:
 ?
----------------------------------------------------------------------------------    

HI scientica:
At first glance - very interesting. Some notes:

1. Maybe it is a little bit strict and complex
For example, why arguments desription is so strict. I think more relaxed definition will be better: "; someword: some description." - someword is the argument name, register or stack.

If the Name does not exist, IMHO it's needless to search for a code.

2. About format: Why not to make simple application with browser, index creation and search function? I even think you can scan the sources in real time - it will be fast enough.

Good work.
Regards.

Remarks

WriteConsole writes characters to a console screen buffer. It behaves like the WriteFile function, except it can write in either Unicode (wide-character) or ANSI mode. To create an application that maintains a single set of sources compatible with both modes, use WriteConsole rather than WriteFile. Although WriteConsole can be used only with a console screen buffer handle, WriteFile can be used with other handles (such as files or pipes). WriteConsole fails if used with a standard handle that has been redirected to be something other than a console handle.

Here is some lines that might be use full:
(I currently use stderr as "debugout".)
harsyra 1> std.out
harsyra > std.out
writes stdout to std.out.

harsyra 2> err.out
writes stderr to err.out.

harsyra 1> std.out 2> err.out
writes stdout to std.out and stderr to err.out.

harsyra | gvim -
sends stdout to gvim (which reads input from stdout, it's the "-" switch's work)
    

Hehe, currently you can type what ever after harsyra[.exe], it'll be ignored (currently test.asm is hard coded).

btw, I didn't know that you can redirect also stderr. That's why I sometimes needed redir.exe. It is no more . Thanks.