Mataya
February 25th, 2000, 04:35 AM
Hi,
I'm having some source files that I want to document.. but not like opening MS Word, and then alt-tabing, and retyping it all into Word document, but, I'd like to format existing block comments, in headers of functions (and similar), and then use some parser, that will put it all in some sort of database, and then I could query data I need, and show it way I want..
Anyway.. here's main idea.. perhaps, my subconsciousness had put some elements of XML basics that I have, and javadoc..
So, I'd like to format block comments like this:
/**
* <source_file>
* <name> MySource1
*/
/**
* <proc>
* <name> MyProc </name>
* This line is not documented, because it is out of tags..
* <desc> This is just a test
* description...
* <author> Joe Blow
* <param>
* <name> x
* <type> integer
* <desc> Some description
* <param>
* <name> y
* <type> integer
* </proc>
*/
/**
* </source_file>
*/
That should produce something like:
INSERT INTO source_file (name) values ('MySource1');
INSERT INTO proc (source_file_name, name, desc, author)
values ('MySource1', 'MyProc', 'This is just a test
description', 'Joe Blow');
INSERT INTO param (source_file_name, proc_name, name, type, desc)
values ('MySource1', 'MyProc', 'x', 'integer', 'Some description');
INSERT INTO param (source_file_name, proc_name, name, type)
values ('MySource1', 'MyProc, 'y', 'integer');
So, parser should be smart enough to know where to use auto-closing tags in order to keep source file clean as possible (like '<param>..<param>..', is same as '<param>..</param><param>..'), etc..
And.. parser should be able to see what tags are describing tables, and what are fields of these tables...
Finally, before reinventing a wheel, I'd like to ask:
1. Is there some existing auto-source-code-documentation system, that is customizable enough to accept all kinds of information (tags), and produce different output (html, word, text - clipboard), that I can format way I want??
2. Is solution laying in XML? Is there some way to avoid few months of studying deepest secrets of XML? And to find 'Learn XML in 2 hours' :-) ??
-( Matija Tomaskovic )-----
http://www.foi.hr/~mtomasko
----------------( Mataya )-
I'm having some source files that I want to document.. but not like opening MS Word, and then alt-tabing, and retyping it all into Word document, but, I'd like to format existing block comments, in headers of functions (and similar), and then use some parser, that will put it all in some sort of database, and then I could query data I need, and show it way I want..
Anyway.. here's main idea.. perhaps, my subconsciousness had put some elements of XML basics that I have, and javadoc..
So, I'd like to format block comments like this:
/**
* <source_file>
* <name> MySource1
*/
/**
* <proc>
* <name> MyProc </name>
* This line is not documented, because it is out of tags..
* <desc> This is just a test
* description...
* <author> Joe Blow
* <param>
* <name> x
* <type> integer
* <desc> Some description
* <param>
* <name> y
* <type> integer
* </proc>
*/
/**
* </source_file>
*/
That should produce something like:
INSERT INTO source_file (name) values ('MySource1');
INSERT INTO proc (source_file_name, name, desc, author)
values ('MySource1', 'MyProc', 'This is just a test
description', 'Joe Blow');
INSERT INTO param (source_file_name, proc_name, name, type, desc)
values ('MySource1', 'MyProc', 'x', 'integer', 'Some description');
INSERT INTO param (source_file_name, proc_name, name, type)
values ('MySource1', 'MyProc, 'y', 'integer');
So, parser should be smart enough to know where to use auto-closing tags in order to keep source file clean as possible (like '<param>..<param>..', is same as '<param>..</param><param>..'), etc..
And.. parser should be able to see what tags are describing tables, and what are fields of these tables...
Finally, before reinventing a wheel, I'd like to ask:
1. Is there some existing auto-source-code-documentation system, that is customizable enough to accept all kinds of information (tags), and produce different output (html, word, text - clipboard), that I can format way I want??
2. Is solution laying in XML? Is there some way to avoid few months of studying deepest secrets of XML? And to find 'Learn XML in 2 hours' :-) ??
-( Matija Tomaskovic )-----
http://www.foi.hr/~mtomasko
----------------( Mataya )-