jaPBdoc

[remi_meier]

Those who know javadoc will like this tool (at least I hope so ).
This tool parses a source code and creates a documentation of it in HTML.
To have a little description to each function and global variable, you have
to use special comments. Furthermore it creates links to the included files.

A special comment looks like this:

Code: Select all

;** functionname
;* some very special description
;* which continues here

or like that for global variables (and LLs and Arrays):

;** g nameofvariable
;* like above

At the moment all comments will be copy-paste into the HTML-file, so this
can cause problems but also adds features (all the tags of HTML).
If there is enough interest, I will add some more features.

Just try out the .BAT in the zip. It will create a documentation of the source
of jaPBdoc.

http://mypage.bluewin.ch/remimeier/zip/japbdoc.zip

greetz
Remi

[remi_meier]

Update:
- Overview added
- The function description in the table now only displays the first part of
the normal description until the first dot. The rest is below in a separate
list with a more detailed description (linked).
- You can now create a description for each parameter, just add a .param
after the ;** comment:

Code: Select all

;** funcname.param
;* descr. for param

That's it for now

[dracflamloc]

This is pretty cool.

[KarLKoX]

Excellent ! I was waiting for this tool for PB for a long time.
Thanks !

[Flype]

yes very nice remi_meier,
also, like always, very 'clean' code.

yet, a must have !

[remi_meier]

Update:
- Structures and interfaces documented. You can now also document an
element in another way: just write a ;* comment behind it when declaring
it in the structure block. The ;** comment for structures and interfaces
needs a "s " or "i " in front of it. Just look at jaPBdoc.pb
- Shortened version vor documenting parameters or elements:

Code: Select all

;** s TEST
;** .elem1
;* desc for elem1
;** s .elem2
;* desc for elem2 ("s " is optional here!)

;** function.param1
;* param1 is cool
;** .param2
;* param2 is better ;)

- the functions, global variables and structures/interfaces are now sorted
in their tables

greetz
Remi

[Flype]

that's great,

1/ Can you add support for Macros ?

for example :

Code: Select all

;** m CountArray
;* Return the number of elements in a one-dimension array.
;** .array
;* User Array. Syntax: CountArray(UserArray()) 
Macro CountArray(array) 
  ( PeekL( @array-8 ) ) 
EndMacro

2/ Also, it might be better to add a space ' ' between each args.

MyProc(Arg1.l, Arg2.l, Arg3.l) looks a little bit better than MyProc(Arg1.l,Arg2.l,Arg3.l)

3/ More, Classic PureBasic Syntax Coloring for the functions, structures, ... may be cool and more readable.

[remi_meier]

Thanks

1) I don't believe that I fogot the macros
added

2) Good idea
added

3) Perhaps later, I modified a bit the overview, it should be a bit better
now.

I also fixed a bug and added warnings when you try to document parameters,
functions/macros or structure fields that don't exist.

greetz
Remi

[remi_meier]

Update:
- Constants (for ;** use with 'c ' or not )

Code: Select all

;** #Constant
or
;** c #Constant
or
#Const = 4 ;* Descr

[remi_meier]

It's me again

Little update:
- A simple filter can be specified as a program parameter, more information
about this is in the jaPBdoc.pb.html after you ran the .BAT.
- Structure fields and procedure parameters are now sorted.
- When you write a _ as the last char of a comment, a line break will be
inserted.

Have fun!
Remi

[remi_meier]

Again made my life easier: You can now write one-line-docus:
;** funcname: Docu for this function
;* continues here
this trick with ':' of course works with every ;** comment.

Much simpler for things like:
;** AddFile: Adds a file.
;** .File: A string with a path to a file.

[remi_meier]

Important update:
- forgot ProcedureDLL and ProcedureCDLL
- you can now specify multiple files at once, then all the structs/interfaces
will be linked to each other in all files.

[Flype]

thank you remi_meier. nice to you.

[remi_meier]

Some parameters added and other things:
- DLL functions get an own table
- if there are no constants, no table will be created. The same for the other
types (structures, functions, etc.)
- added ReadMe.html
- Parameters:
/notstart
/onlystart
/onlydll
/nodlltable
/nofunctions
/noglobals
/nostructs
/noconstants
For a little description read the ReadMe.html.

If something is missing, just tell me and I will think about it

greetz
Remi

[#NULL]

i needed to update jaPBDoc for PB 5.42 and added some things.
i used the version from here (2008) : http://forums.purebasic.com/german/view ... 68#p184768
and merged it with some of my changes and fixes.

DOWNLOAD:
http://www.wannabephoenix.de/PB/jaPBDoc ... -04-30.zip

Code: Select all

----------------------------------------------
2016-30-04

- fixed problem with sources that do not contain structures/interfaces
- fixed problem if procedure calls are used for variable initialization
- added support for List/Array/Map keywords in procedure argument declarations


----------------------------------------------
2016-29-04

- added support for 'NewMap' declarations
- fixed handling of declarations of array/lists/maps of pointers (both were working independently but not in combination)
- added paramters:
	/nosortparam
		Don't sort procedure arguments.
	/nosortfield
		Don't sort structure fields.
	/nosortpafl
		Don't sort procedure arguments and structure fields.
	/nosort
		Don't sort anything.
- added missing paramter documentation in ReadMe.html:
	/stylesheet
		The next parameter is a stylesheet filename that will be linked in the resulting html file.
- fixed missing removal of %STYLESHEET% placeholder in template if no stylesheet is specified

adapted code to PB 5.42:
- some function pointers now integer
- using Bool() where necessary
- using 'List' keyword in procedure declaration
- changed #PB_Sort_String to #PB_String
- changed an array name to 'array_' to not conflict with the new PB keyword 'Array'

----------------------------------------------

i didn't touch the linux code.


there is still an issue: i think the readme is wrong about that:

All this one-liners won't change the target (set by a ;**-comment), but also won't add anything to it

Code: Select all

;** g a : doc_a
Global a.l
Global b.l ;* doc_b

'doc_b' is added to both documentations and if you do it like this

Code: Select all

Global a.l ;** g a : doc_a
Global b.l ;** g b : doc_b

it works but you get a warning for each about overwriting a documentation.
what worked for me in this case was resetting the target from 'a' to nothing

Code: Select all

;** g a : doc_a
Global a.l
;**
Global b.l ;* doc_b