SDB Engine

Welcome to the SDB Engine forum!

Skip to content




Welcome
Welcome to the SDB Engine Forum!
You are currently viewing our boards as a guest, which gives you limited access to view most discussions and access our other features. By joining our free community, you will have access to post topics, communicate privately with other members (PM), respond to polls, upload content, and access many other special features. Registration is fast, simple, and absolutely free, so please, <a href="/profile.php?mode=register">join our community today</a>!

GetDoc 1.0

Hollywood applications release by me

GetDoc 1.0

by Allanon on 13 Jun 2008, 15:50

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
Image
Attachments
GetDoc.txt
=== INSTRUCTIONS ===
(4.11 KiB) Downloaded 24 times
GetDoc_Win32.lha
Win32
(602.33 KiB) Downloaded 14 times
GetDoc_WarpOS.lha
WarpOS
(391.75 KiB) Downloaded 10 times
GetDoc_OS4PPC.lha
OS4 PPC
(551.2 KiB) Downloaded 23 times
GetDoc_MorphOS.lha
MorphOS
(505.94 KiB) Downloaded 11 times
GetDoc_MacOSPPC.lha
MacOS PPC Version
(429.05 KiB) Downloaded 7 times
GetDoc_Classic68k.lha
Classic Amiga 68k Version
(368.4 KiB) Downloaded 18 times
GetDoc_AROS.lha
AROS Version
(507.43 KiB) Downloaded 15 times
Allanon
Site Admin
 
Posts: 63
Joined: 22 Mar 2007, 22:50

by Clyde on 14 Jun 2008, 21:30

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
CD32 + SX1; AmiKit (WinUAE) + OS3.9
Clyde
 
Posts: 37
Joined: 27 May 2008, 19:38
Location: Dresden / Germany

by Clyde on 22 Jun 2008, 10:46

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
CD32 + SX1; AmiKit (WinUAE) + OS3.9
Clyde
 
Posts: 37
Joined: 27 May 2008, 19:38
Location: Dresden / Germany

by Allanon on 22 Jun 2008, 15:53

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
Site Admin
 
Posts: 63
Joined: 22 Mar 2007, 22:50

by Clyde on 22 Jun 2008, 20:55

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.
CD32 + SX1; AmiKit (WinUAE) + OS3.9
Clyde
 
Posts: 37
Joined: 27 May 2008, 19:38
Location: Dresden / Germany

by Allanon on 22 Jun 2008, 21:18

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 :wink:

P.S.: to have a fully functional amigaguide remember to set at least one node with the name "Main" :D
Allanon
Site Admin
 
Posts: 63
Joined: 22 Mar 2007, 22:50

by Clyde on 22 Jun 2008, 22:27

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 :wink:

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


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
CD32 + SX1; AmiKit (WinUAE) + OS3.9
Clyde
 
Posts: 37
Joined: 27 May 2008, 19:38
Location: Dresden / Germany

by Allanon on 23 Jun 2008, 10:14

... 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?
:wink:
Allanon
Site Admin
 
Posts: 63
Joined: 22 Mar 2007, 22:50


Return to Released by me

Who is online

Users browsing this forum: No registered users and 0 guests