This documentation is so bad it's SHAMEFUL

BlitzMax Forums/BlitzMax Programming/This documentation is so bad it's SHAMEFUL

CoderLaureate(Posted 2005) [#1]
Ok, I've just spent the last 45 minutes trying to find a list of Escape codes used in BMax Strings, and to no avail. Could someone please point me in the right direction?

Searchable documentation would be a really neat thing guys.


Perturbatio(Posted 2005) [#2]
language->literals


CoderLaureate(Posted 2005) [#3]
Thank you


Yan(Posted 2005) [#4]
Language>Literals

[edit]
That's what I get for trying to be clever and looking for it on the wiki as well. ;o)
[/edit]


FlameDuck(Posted 2005) [#5]
So in fact it's not the documentation that's bad, but the way you can access it?


MrCredo(Posted 2005) [#6]
BOTH is bad


FlameDuck(Posted 2005) [#7]
Compared to what? In my experience it's not particularly worse than MSDN (which will let you search, but more often than not, return incorrect and/or useless pages).


Muttley(Posted 2005) [#8]
The only issue I have with the docuemntation is the lack of well-commented example code for some stuff.

A lot of the samples also have either very little, or nothing at all in the way of useful comments.

Muttley


Robert Cummings(Posted 2005) [#9]
The main entry point to the docs are the commands which you often need to see related uses of: for exampe, graphics, when you Hit F1 twice, does not have a link to the docs for it.

Which is quite a large oversight considering. I have faith they will be tidied up eventually.


MrCredo(Posted 2005) [#10]
The docs are INCOMPLETE - i find many many many function-parameters without description...

Function FormatTextAreaText( textarea:TGadget,r,g,b,flags,pos=0,length=-1,units=1 )

what is flags?
what is units?
why length=-1?

and the same with 50% of all commands...


Compared to what?

compared to my old german BB2D/3D/Plus docs:
http://www.blitzbase.de/4a.htm
(and the download version with frames is much better than the online version)


CoderLaureate(Posted 2005) [#11]
What we need is a manual. Remember those? They were great. They listed commands, gave descriptions, samples. Each broken down into sections in a logical order.

Hell, I'd pay money for a good paper back BMax manual.

-Jim


Mark Tiffany(Posted 2005) [#12]
Searchable documentation would be a really neat thing guys.

Added as a high priority feature request in the Community Edition of the IDE. I think that in many cases (but not all) the docs are there, just not easily accessible, and search will really help this. There are lots of missing examples though.


FlameDuck(Posted 2005) [#13]
and the same with 50% of all commands...
Don't be rediculous. More than half of the commands don't even have arguments.

compared to my old german BB2D/3D/Plus docs:
Why not help do the same for the BlitzMAX docs then?

Hell, I'd pay money for a good paper back BMax manual.
Undoubtedly. But probably not enough to - on it's own - justify the time and commitment nessecary to provide such documentation.


Steve Elliott(Posted 2005) [#14]

What we need is a manual. Remember those? They were great. They listed commands, gave descriptions, samples. Each broken down into sections in a logical order.

Hell, I'd pay money for a good paper back BMax manual.



Absolutely! I've still got my Blitz3d one. It's also helpful when not at the computer when working some things out on paper. You can then refer to the manual to check command syntax and usage.

The problem is the language is still being refined. The 3d module isn't out yet and the 2d module (quite rightly) is being optimized (for 2d in 3d cool stuff).

I quite often find myself confused over syntax and application because Max has moved so far from the Blitz BASIC syntax and is similar in-part - but not completely like C++. For example the new pointer syntax is ridiculous - just use C++ syntax for pointers please.


Robert Cummings(Posted 2005) [#15]
Must be that time of the month again eh Mikkel?
You must have really, really low standards.