Documentation generator for Blitz programs

Community Forums/Showcase/Documentation generator for Blitz programs

RepeatUntil(Posted 2003) [#1]
I have written a documentation generator. This generator takes a blitz program, retrieves the comments in the program (function, arguments of function, variables, types, ...) and creates a html file documenting the program.
It permits to keep a documentation of what you have written, readable by everyone, or even by yourself when you look at your program 6 months later.
I will release it at the beginning of september, but first I have some questions/advices to ask to you.
1/ I didn't find a title for that application. I know that the imagination of the blitz community is without limit: anyone has an idea ???
2/ What kind of features will you wish to see included in this kind of application ?
3/ Do you think that it's possible to release it as a shareware ? (people who are happy with it can pay something like 5 to 10 $/€) Not sure that it can work though ;)

Thanks for you answers!!


Koriolis(Posted 2003) [#2]
1) BlitzDoc would be an easy solution, but I think it's already taken (isn't there such a tool already somewhere?)
2) It should have features like JavaDoc (by example special keywords in the comments to describe the parameters, the return value...)
3) NO! Sorry to say that, but it's a little bit too "light" to be sold IMHO. I have personnaly written a doc generator when I made my OO preprocessor (that I finally dropped BTW), which makes a full documentation of the classes, with crossed links, method descriptions, class hirerarchy display, links to overriden methods, etc. And I found it pretty easy to do, so...
But nothing prevents you from trying. Maybe if you have very strong features some people might be interested (I'm sceptical though).

PS: I'm really not saying such a tool is not worth it (or I wouldn't have made one!), I'm just guessing few people will be willing to pay for it. I may be wrong.


poopla(Posted 2003) [#3]
I am willing to pay for it if it has the potential to produce nice documentation files. I don't have time to code that myself atm.


dan_upright(Posted 2003) [#4]
the artist formerly known as warpy wrote one of these a while back, but his site's gone now so i couldn't tell you where it is


myspys(Posted 2003) [#5]
no offence, but why is everyone so obsessed with making money from their code?

i thought people coded for fun (unless it's your job)


Koriolis(Posted 2003) [#6]
Maybe because spending hours of coding and experimenting just for fun doesn't help much to pay your phone bill ;)


Michael Reitzenstein(Posted 2003) [#7]
Why is code any different to any other good produced by other hobbyists? Just because the variable cost of reproducing code/programs is ridiculously low, why should someone who makes furniture as a hobby sell their produce without anyone thinking twice about it and yet someone who codes and sells their creation be criticised for it?

If anybody wishes to sell their projects, the best of luck to them. Anybody that doesn't, I even encourage them to. That's not to say that they should just go and put a price tag on their mediocre products - we need more products with enough value to be sold and less half finished unsupported ones, even if we have to pay for them!


myspys(Posted 2003) [#8]
koriolis, that's why you get a job ;)


Koriolis(Posted 2003) [#9]
Ohhh, so that's it?!? Thanks a lot, mypsis. Why must I always the last one aware of things? ;)
Michael Reitzenstein > Well said, agreed.


dangerdave(Posted 2003) [#10]
Sorry to hijack your thread RepeatUntil.

To name a few, I paid for my:
operating system, my 2d graphics program,
my 3d graphics program, my texture (un)wrapping program,
my programming language - Blitz Basic 3D.

All were made by code.


myspys(Posted 2003) [#11]
i didn't say code isn't worth paying for

it just seems like everyone who's written a "hello world"-snippet wants to charge for it, which i find odd and weird


RepeatUntil(Posted 2003) [#12]
@myspys:
"no offence, but why is everyone so obsessed with making money from their code?
i thought people coded for fun (unless it's your job)"
-> Because it's fun to have money from my fun !!

Anyway, I was just asking for a shareware payment: only people who whish to give money (OK, nobody!) can send money. I would find it funny even to receive 5$ for my work!!

But no matter, it was just a question. Thanks for giving your opinion.
Now I need urgently a name for the application: apart from the easy "BlitzDoc", anyone has a tremendous idea ??


semar(Posted 2003) [#13]
How about:

- Blitz DOC_GEN
- REM (or Blitz REM)
- CODOC (COde DOCument)
- BTD (Blitz To Doc)
- Hyper Blitz
- DOC BOT (DOCumentation roBOT)
- BC/AC (Blitz Code/Auto Comments)

Sergio.


Red Ocktober(Posted 2003) [#14]
I wouldn't mind paying a guy a reasonable sum for his hard work, especially if...

(1)it entertained me
(2)it was a valuable utility

As a matter of fact, I've licensed a few things from Blitz developers here...

As far as doc generation tools, would DOxygen also work with Blitz source files?

--Mike


RepeatUntil(Posted 2003) [#15]
At 95% confidence level, the name chosen for this documentation generator would be:
Blitz2Doc
It should be released at the beginning of September. Blitz2Doc is intented to document your code with html files. I write it keeping the idea in mind that the coder has to do the least modification as possible to implement comments understood by Blitz2Doc. Everything should be very intuitive.
The features of Blitz2Doc will be:
- document constant variables, global variables, array, types, functions (arguments, return value, examples), or choose to include only a subset of these
- Option to document functions in separate html files (like the Blitz command reference)
- You can group variables or functions linked to the same functionnality together in the documentation
- Possibility to document one file, a whole directory, or directories and all its subdirectories
- Put links, different fonts or pictures in your documentation
- Two possible styles for html documentation: BlitzBasic or Blitz2Doc
- Very simple to use thanks to the Graphical Interface
- The possibility to implement it easily in any IDE
- And Blitz2Doc will come with a complete help file and a some examples to start quickly
- and more...


Koriolis(Posted 2003) [#16]
Sounds good I must say. Maybe I'll purchase it finally.
Anyway, I was just asking for a shareware payment: only people who whish to give money (OK, nobody!) can send money. I would find it funny even to receive 5$ for my work!!
That's fair :) You could even get more paying users that way than if you add a fixed price (even as low as 5$). Good luck with it.


Who was John Galt?(Posted 2003) [#17]
Yeah I also agree with Rice n' Stein- I'm all for trying to flog something you made. Potential buyers will be the judge of whether it's worth the $ or not. What coder doesn't at least dream of one day selling some of their stuff?


Zace(Posted 2003) [#18]
Best plan would be to release it and make sure people visit your webiste where there are screenshots, instructions, maybe a demo, and most of all a donation paypal button!

Good luck.


Giano(Posted 2003) [#19]
I've done this a year ago (I think) and the mass forget it...probably isn't so good...

Try and tell
http://www.hermesartstudios.com/users/intensiveworks/projects/bloop/index.html

ciao
Gianluca


RepeatUntil(Posted 2003) [#20]
Hi BitmaniaK,

I tried your Bloop software. I was impressed by the very good quality of your product. It's a pity that the mass forget it. Try to re-release it!!!

But Blitz2Doc is nothing to see with your product (which is creating special functions related to type). Blitz2Doc takes your Blitz code (with commments which follow some very simple and intuitive rules) and create an html documentation. It's a tool to help you to document your code, for you and for people looking to your code!!


Giano(Posted 2003) [#21]
Sorry...I've done a mistake...Bloop was developed 1 year ago and my blitz documentation tool too...So I linked the wrong program...
Now I'm looking in my home folders to retrieve it...be patience I will put it on web asap.
Sorry for the time lost :)
Cya

Gianluca


Giano(Posted 2003) [#22]
Here we are...

Blitz2doc2

Check this link, download and test it..
It uses blitzsys for opening request file but can be modified to use userlibs...

Works also drag&drop of multiple files :)

http://www.hermesartstudios.com/users/intensiveworks/projects/blitz2doc2/blitz2doc2.zip

Ciao
Gianluca


RepeatUntil(Posted 2003) [#23]
Hi BitManiak,

I test your program. I think it's a good basis for a documentation generator, but there is a lack of options compared to well-known documentation generator like JavaDoc.
My program is more extended, with a lot of options that the user can choose. I have to say that I spent a very long time on it during my vacations (much more than I thought when I decided to start this project!), and I have still a lot of ideas to implement on it. My program will have basically all the capabalities of JavaDoc (crossed link, lot of useful tags,...), plus a lot of capabilities that I have added (2 predefined styles, user defined styles, document function in separate file like Blitz Basic documentation, frame - no frame, intuitive format for comments, GUI to launch it easily with options,...).

Now I hope that people will be interested by this program. I think it's very useful (now I am using it even myself), but I really hope people won't miss it!!

Now concerning the name of your program: I think there is conflict between our 2 names. I called mine Blitz2Doc. And I see you called it (one year ago) Blitz2Doc2 (in this thread) or BlitzDoc2 (when the program is launched). So first, what is its name ? BlitzDoc2 or Blitz2Doc2 ??
So our names are too close. As you have the paternity of the name, I guess that you don't wish that my program is called Blitz2Doc. Let me know what you think, I can still change the name of my application!!

Thanks,


Giano(Posted 2003) [#24]
Mine is free and as is...no copyright on it...
I've named so because is the natural name of a tool of this kind :)
Is based on a previous tool name blitz2doc or blitzdoc (don't remember) given with the original blitz package (the one I bought a lot of time ago) so the name isn't original..(that's why the II).
Call it as you like..if your program is really as you say and you give me as free :)...I will cut my name and the project enterely (or simply will change my name )

ciao