SDB Engine

Hello,
You can dowload here GetDoc 1.0, a program developed to extract documentation from source code.
You have to follow simple rules to comment your code and with this tool you can easily build Amigaguide files with the documentation extracted from the soruce code.

At the bottom of this post you can download the appropriate distribution, you can choice from:
- Amiga Classic
- Amiga OS4
- AROS
- Win32
- MorphOS
- WarpPPC
- MacOS

Note that I've tested only the Amiga Classic (under WinUAE)and the AROS versions.


Here is a Cut & Paste of the included guide:

Code: Select all

   +--------------+
   | INSTALLATION |----------------------------------------------------------
   +--------------+
   To install the program, uncompress in a drawer of your choice and ensure
   that the provided fonts are installed on your system, if you wish, you can
   put the provided fonts in the program drawer.

   +--------------+
   | INTRODUCTION |-----------------------------------------------------------
   +--------------+
   <GetDoc> is a tool that can be used to extract documentation stored in
   a source code file.
   The result of this operation is an AmigaGuide file with an index of all
   nodes defined inside the source code.
   You have to follow some simple rules described below:

   | SINGLE LINE TAGS |
   +------------------+
   GetDoc supports the following tags to define some global informations:
   <APP_NAME>       Define the application's name
   <APP_VERSION>    Define the application's version
   <APP_AUTHOR>     Define the application's author

   | MULTILINE TAGS |
   +----------------+
   Multiline tags are used to define the starting position of a new section (node)
   all subsequent lines will be included in the defined node unless another
   node is defined or the current one is explicitly terminated.
   Here are the tags provided:
   <NODE>        Define a new node
   <-8<--->      Terminate the current node

   | LINKS |
   +-------+
   Inside a node section you can define links with the tag LINK followed by
   the name of a valid node.
   These links will be listed all together at the end of the node.

   +-------+
   | NOTES |-----------------------------------------------------------------
   +-------+
   The -8<--- tag is usefull when you are documenting functions because you
   can close the current node leaving out all code comments.
   Actually this tool is written with Hollywood in mind but can handle all
   languages that support single line comments.
   Default is <;> but you can switch the comment type using the interface
   of GetDoc.

   +------------------+
   | GETDOC INTERFACE |------------------------------------------------------
   +------------------+
   The interface is minimalist, there is a box for the source file and one for
   the destination file, where your Amigaguide file will be saved.
   There are three more options:
      <Auto Open Guide>    If you select this switch, when the process is terminated
                           the guide will be opened.
                           Remmber that if you select this option the program will
                           try to open the guide with Multiview (SYS:utilities/Multiview)
                           so this option is valid only for system that support/have
                           Multiview.
      <Sort Master Index>  This switch is used to alphabetically sort the master
                           index of all available nodes.
      <Comment Type>       Select here which type of single line comment you
                           want to parse in the selected source code.
   When all is in place press the button <Extract Docs> and your Amigaguide file
   will be generated.

   +-------------+
   | FINAL NOTES |------------------------------------------------------------
   +-------------+
   This tool was born because my need to have a simple tool to build documention
   for ScuiLib.
   
   Finally, GetDoc is written using Hollywood 3.1 and ScuiLib for the GUI.


Please report any bug you may encounter!

Screenshot

Hey Fabio,

very cool! Seems to be a useful tool. I will try it out soon and report my experience. Thanks for that, mate!

Greetings
Micha

Hi Fabio,

would it be possible to add support for multiline comments like /* and */ ? I guess this will be a "bit" more difficult to realize. But would be a nice and useful feature.

Greetings
Micha

I could add support for multiline code but this will adds more work to decode the tags and without a real improvement in features, let's see an example:

Currently supported single line comment:

Code: Select all

; NODE TestingGetDoc
;   This is a test, do you like it?
;   I hope you will find it usefull
;
;  -8<---


If you have another node consecutive to this one and no code comments between the two nodes you can omit the closing tag -8<---

With support for multiline comments:

Code: Select all

/* NODE TestingGetDoc
   This is a test, do you like it?
   I hope you will find it usefull

*/


I can't see improvements in the last case...
Do you have an example where supporting multiline comments could be usefull? Maybe I'm missing a real case example

Allanon wrote:I can't see improvements in the last case...
Do you have an example where supporting multiline comments could be usefull? Maybe I'm missing a real case example

Yeah, normally you are absolutely right. Nevertheless I can give you an example: Someone at Amiga Resistance wanted to create these amigaguides with the source code Andreas created. And he used /* and */ (with the additional parser difficulty that ** is in front of every comment, too). Or in general: Creating amigaguides from existing porjects, that use the multiline comments.

mmm... are you talking of a structure like this ?

Code: Select all

/****************************************************************
**                                                             **
** Name:        CreditsRoll                                    **
** Author:      Andreas Falkenhahn                             **
** Version:     1.3                                            **
** Date:        15.09.05                                       **
** Interpreter: Hollywood 2.0                                  **
** Licence:     Sample program for Hollywood                   **
** Function:    Hollywood Designer credits                     **
**                                                             **
** Contact:     Andreas Falkenhahn                             **
**              An der Trift 2                                 **
**              36132 Eiterfeld-Arzell                         **
**              GERMANY                                        **
** E-Mail:      andreas@airsoftsoftwair.de                     **
** Internet:    http://www.airsoftsoftwair.com/                **
**                                                             **
** Notes: This is the same scroller as seen in Hollywood       **
** Designer 1.0 "About" window.                                **
**                                                             **
** History:                                                    **
**                                                             **
** 1.3: (15.09.05)                                             **
**                                                             **
** - adapted for Hollywood 2.0                                 **
**                                                             **
** 1.2: (16.11.03)                                             **
**                                                             **
** - some minor issues for Hollywood 1.9                       **
**                                                             **
** 1.1: (31.05.03)                                             **
**                                                             **
** - adapted for Hollywood 1.5                                 **
**                                                             **
** 1.0: (27.10.02)                                             **
**                                                             **
** - initial release                                           **
**                                                             **
****************************************************************/

/*
** Important! Check if the used Hollywood version is at least
** version 2.0!
*/


If I have understood right it's very simple to extract this informations with few modification of the source code, like the following:

Code: Select all

; NODE Main
;/****************************************************************
;**                                                             **
;** Name:        CreditsRoll                                    **
;** Author:      Andreas Falkenhahn                             **
;** Version:     1.3                                            **
;** Date:        15.09.05                                       **
;** Interpreter: Hollywood 2.0                                  **
;** Licence:     Sample program for Hollywood                   **
;** Function:    Hollywood Designer credits                     **
;**                                                             **
;** Contact:     Andreas Falkenhahn                             **
;**              An der Trift 2                                 **
;**              36132 Eiterfeld-Arzell                         **
;**              GERMANY                                        **
;** E-Mail:      andreas@airsoftsoftwair.de                     **
;** Internet:    http://www.airsoftsoftwair.com/                **
;**                                                             **
;** Notes: This is the same scroller as seen in Hollywood       **
;** Designer 1.0 "About" window.                                **
;**                                                             **
;** History:                                                    **
;**                                                             **
;** 1.3: (15.09.05)                                             **
;**                                                             **
;** - adapted for Hollywood 2.0                                 **
;**                                                             **
;** 1.2: (16.11.03)                                             **
;**                                                             **
;** - some minor issues for Hollywood 1.9                       **
;**                                                             **
;** 1.1: (31.05.03)                                             **
;**                                                             **
;** - adapted for Hollywood 1.5                                 **
;**                                                             **
;** 1.0: (27.10.02)                                             **
;**                                                             **
;** - initial release                                           **
;**                                                             **
;****************************************************************/

;/*
;** Important! Check if the used Hollywood version is at least
;** version 2.0!
;*/
;-8<---


As you can see just add a semicolon to the beggining of the line and the keyword NODE to achieve the result.
If you wish I can add the double asterisk as single comment marker to support Andreas commenting style, but you have to modify the code to add the NODE keyword and if necessary the end-node marker ( -8<--- ).

Remember that you have to modify existing project to extract docs because GetDoc can't know what you want to document and what you don't want so you have to add manually the sections with the NODE keyword followed by the name of the node.

Let me know what do you think about it

P.S.: to have a fully functional amigaguide remember to set at least one node with the name "Main"

Yes, you are right, I exactly meat such an example!

Allanon wrote:As you can see just add a semicolon to the beggining of the line and the keyword NODE to achieve the result.
If you wish I can add the double asterisk as single comment marker to support Andreas commenting style, but you have to modify the code to add the NODE keyword and if necessary the end-node marker ( -8<--- ).

Yeah, would be cool if you could add it. Just in case ...

Well, yeah, it is not so complicated to edit the file via search/copy/paste, but it can be time-consuming. Would it be possible (or would it make sense ), if GetDoc would automatically add the semicolon before every comment line temporary just for creating the guide?

Allanon wrote:Remember that you have to modify existing project to extract docs because GetDoc can't know what you want to document and what you don't want so you have to add manually the sections with the NODE keyword followed by the name of the node.

Let me know what do you think about it

P.S.: to have a fully functional amigaguide remember to set at least one node with the name "Main"

Hm, what if you would implement a "lazy mode"? This means, that I have not to edit the source file, but GetDoc would add semicolon (see above), adds _every_ comment to document and also adds the Main tag automatically (at the beginning of guide). Well, that is just a quick thought. I am not really sure, whether it would make sense or is practical. :-/ What do you think?

Greetings

... GetDoc can't add semicolon for you because it can't know which are comment line and which not, at least I can do the following:

- Add support for double asterisk (**)
- Place all selected lines outside nodes into a dummy node named "* Missing Header *", or, if the "Main" node is not defined, the program will create a "Main" node and place all these lines into this section.


In your specific case all lines starting with a "**" will became part of the Main node by default and correctly displayed in a single-node Amigaguide file.
So, with the new version, you should:
- Selected "**" as comment line style
- Set the new switch on (see below)
Remember that all lines starting with semicolon will be discarded (because of the ** ).

To preserve compatibility with the main purpose of this tool I will add a switch named:
- Collect Not-In-Node lines
Setting this switch on will activate the above procedure, otherwise all not-in-node lines will be discarded preserving the original processing mode.

In a standard case all collected lines will go under the node "* Missing Header *" and displayed like a normal node.

Can this solve your problem?