gdoc for CP/M: documentation generator from sources

[FloppySoftware]

Hi!

I have just added a new CP/M native program to my retro-projects in GitHub: gdoc, a documentation generator from C and assembler sources.

It has certain compatibility degree with doxygen, and it's able to output the documentation in plain text or HTML formats.

Maybe it's of your interest!

GitHub - MiguelVis/RetroProjects: My retro programming projects for some

[TFM]

So what exactly does it do? Is it a TXT to HTML converter?

[AMSDOS]

Sounds like both. 

[FloppySoftware]

Ok, let's go for a couple of examples.

C source code:

Code Select Expand

/**
* @file
*
* @brief The purpose of this file is to test the gdoc program.
*
* The gdoc program is a documentation generator for MESCC source code files (and
* presumably other sources for c-like compilers).
*
* It is written to be simple but effective, and it has some degree of
* compatibility with other documentation generator tools as doxygen or javadoc.
*
* @author  Miguel I. Garcia Lopez / FloppySoftware
* @version 1.00
* @date    10 Apr 2016
*/
#include <mescc.h>
#include <printf.h>
/**
* @fn     main(int argc, WORD argv[]) : int
*
* @brief  The main function.
*
* This function will be called on the first place. The second
* argument would be 'char *argv[]' in standard C.
*
* @param argc - the number or arguments given in the command line
* @param argv - the arguments (#0 is the program name)
*
* @return the success / error / whatever code
*/
int main(argc, argv)
int argc; WORD argv[]; // MESCC doesn't support char *argv[] -- pity
{
/* Say hello */
hello("Hello!");
/* CP/M doesn't store the name of the program -- pity */
argv[0] = "test.com";
/* Print the name of the program */
program(argv[0]);
/* Print the arguments if any */
params(--argc, &argv[1]);
/* Say bye */
bye();
}
/**
* @fn    hello() : void
*
* @brief Say hello (or something)
*
* Say hello, or whatever the message is passed as an argument.
*
* @param msg - the message
*/
hello(msg)
char *msg;
{
printf("%s\n\n", msg);
}
/**
* @fn    program(char *name) : void
*
* @brief Print the program name.
*
* Print the name of the program, given as a parameter.
*
* @param name - the program name
*/
program(name)
char *name;
{
printf("I am %s, a humble program.\n\n", name);
}
/**
* @fn    params(int num, WORD what[]) : int
*
* @brief Print the program arguments.
*
* Print the arguments given in the command line, if any. The second
* argument would be 'char *argv[]' in standard C.
*
* @param num - the number of arguments
* @param what - the arguments
*
* @return the number of arguments
*/
params(num, what)
int num; WORD what[];
{
int i;
/* Print the arguments, if any */
if(num) {
  /* Print the arguments */
  for(i = 0; i < num; ++i) {
   printf("Param #%d = %s\n", i, what[i]);
  }
}
else {
  /* There are no arguments */
  printf("There are no arguments on the command line.\n");
}
putchar('\n');
/* Return the number of arguments */
return num;
}
/**
* @fn    bye() : void
*
* @brief Say bye.
*
* Say bye to the user. This function should be
* the last called function in the program, but who knows.
*/
bye()
{
printf("Bye, bye!\n");
}


Text output:

Code Select Expand

=======
testc.c
=======
The purpose of this file is to test the gdoc program.
Author:
   Miguel I. Garcia Lopez / FloppySoftware
Version:
   1.00
Date:
   10 Apr 2016
The gdoc program is a documentation generator for MESCC source code files (and
presumably other sources for c-like compilers).
It is written to be simple but effective, and it has some degree of
compatibility with other documentation generator tools as doxygen or javadoc.
Functions:
   main(int argc, WORD argv[]) : int
     -The main function.
   hello() : void
     -Say hello (or something)
   program(char *name) : void
     -Print the program name.
   params(int num, WORD what[]) : int
     -Print the program arguments.
   bye() : void
     -Say bye.
---------------------------------
main(int argc, WORD argv[]) : int
---------------------------------
The main function.
This function will be called on the first place. The second
argument would be 'char *argv[]' in standard C.
Parameters:
   argc - the number or arguments given in the command line
   argv - the arguments (#0 is the program name)
Returns:
   the success / error / whatever code
--------------
hello() : void
--------------
Say hello (or something)
Say hello, or whatever the message is passed as an argument.
Parameters:
   msg - the message
--------------------------
program(char *name) : void
--------------------------
Print the program name.
Print the name of the program, given as a parameter.
Parameters:
   name - the program name
----------------------------------
params(int num, WORD what[]) : int
----------------------------------
Print the program arguments.
Print the arguments given in the command line, if any. The second
argument would be 'char *argv[]' in standard C.
Parameters:
   num - the number of arguments
   what - the arguments
Returns:
   the number of arguments
------------
bye() : void
------------
Say bye.
Say bye to the user. This function should be
the last called function in the program, but who knows.

HTML output:

Code Select Expand

<!DOCTYPE html>
<html>
<head>
  <title>testa.zsm</title>
<head>
<body>
  <h1>testa.zsm</h1>
  <p>A test for gdoc.<p>
  <dl>
   <dt>Author:</dt>
   <dd>Miguel Garcia / FloppySoftware</dd>
  </dl>
  <dl>
   <dt>Functions:</dt>
   <dd><a href="#fn0">say</a></dd>
   <dd>&nbsp;- Prints a string on screen</dd>
  </dl>
  <h2 id="fn0">say</h2>
  <p>Prints a string on screen<p>
  <p>
   This function simply prints a string on screen,
   using the BDOS function #9. The string must to
   be terminated with a '$' character.
  <p>
  <dl>
   <dt>Parameters:</dt>
   <dd>de - messaje</dd>
  </dl>
  <dl>
   <dt>Returns:</dt>
   <dd>all registers destroyed</dd>
  </dl>
</body>
</html>

Assembler source code:

Code Select Expand

;(
; @file
; @brief A test for gdoc.
;
; @author Miguel Garcia / FloppySoftware
;)
org 0100h

ld   de,hello
call say
jp   0

;(
; @fn     say
; @brief  Prints a string on screen
;
; This function simply prints a string on screen,
; using the BDOS function #9. The string must to
; be terminated with a '$' character.
;
; @param  de - messaje
; @return all registers destroyed
;)
say:
ld   c,9
jp   5
hello:
defb 'Hello$'

Text output:

Code Select Expand

=========
testa.zsm
=========
A test for gdoc.
Author:
   Miguel Garcia / FloppySoftware
Functions:
   say
     -Prints a string on screen
---
say
---
Prints a string on screen
This function simply prints a string on screen,
using the BDOS function #9. The string must to
be terminated with a '$' character.
Parameters:
   de - messaje
Returns:
   all registers destroyed

HTML output:

Code Select Expand

<!DOCTYPE html>
<html>
<head>
  <title>testa.zsm</title>
<head>
<body>
  <h1>testa.zsm</h1>
  <p>A test for gdoc.<p>
  <dl>
   <dt>Author:</dt>
   <dd>Miguel Garcia / FloppySoftware</dd>
  </dl>
  <dl>
   <dt>Functions:</dt>
   <dd><a href="#fn0">say</a></dd>
   <dd>&nbsp;- Prints a string on screen</dd>
  </dl>
  <h2 id="fn0">say</h2>
  <p>Prints a string on screen<p>
  <p>
   This function simply prints a string on screen,
   using the BDOS function #9. The string must to
   be terminated with a '$' character.
  <p>
  <dl>
   <dt>Parameters:</dt>
   <dd>de - messaje</dd>
  </dl>
  <dl>
   <dt>Returns:</dt>
   <dd>all registers destroyed</dd>
  </dl>
</body>
</html>

Summary: It's a CP/M native tool to generate documentation for programmers from C / assembler sources (easily adapted to other languages).

+/- like doxygen does, effective, but with a lot less functionality.

For freaks like me that like to do programming with native tools under CP/M.

[TFM]

Great job done!!!    Thank's for explaining!!!