Max Documentation
BlitzMax Forums/BlitzMax Beginners Area/Max Documentation
| ||
| Well my BlitzMAX shaped Christmas present is here and it's looking fairly good so far except I'm having more difficulty getting into the language than I thought I would. The language is different from Blitz3D but not radically different and I've come to the conclusion that it's the documentation that is making things more difficult than perhaps it should. Perhaps I've been spoilt with the Blitz3D documentation which is really good because most commands have examples and example code. MAX however has a really bad way of doing things. I don't know about others but to me when I read Function LoadImage:TImage( url:Object,flags=-1 ) It's not immediately apparent that it means... Global sand:TImage = LoadImage("C:\sand.png") where Timage is a new more effective way of having a handle. Are there any plans to improve the documentation? One of the reasons I was able to pick up Blitz3D so quickly was the documentation. Looks like it may be more of a struggle this time around |
| ||
| if im not mistaken that is the oop way with using Strict if you dont use strict or oop it can be just Image = LoadImage("Image") but i could be way off lol im new to all things blitz |
| ||
| IMHO, that's a *bad* habit to be getting into (search for the hundreds of 'why is my program leaking memory' posts if you don't believe me), embrace the way of the object! :o) The BlitzWiki is a bit of an improvement over the built in docs generally, it's still just as bad in places though. |
| ||
| Yeah I know you can just use Image = LoadImage("Image") but what I'm saying is from the documentation you wouldn't even get that I don't think. |
| ||
| i wrote a documentation tool http://www.blitzbasic.com/toolbox/toolbox.php?tool=142 it is much better to read... but - this program get all infos from module sources. And if a parameter is not described - you have the same situation. |
| ||
| it's still just as bad in places though. That's because, in places, it's just a direct copy of the docs. People need to add to it in order to make it worthwhile. |
| ||
| I've got to say I'm disappointed that there doesn't seem to be any official effort to improve documentation, if their were they'd have posted a response. |
| ||
| It's not immediately apparent that it means... That's not exactly what it means. The "url:Object" can refer to much more than a simple String. It can refer to a stream, bank or other related object, like a pixmap aswell. |
| ||
| :Type is quite descriptive enough if one read the OO part of the language documentation first and understands that this means that an instance of the class "type" is returned and thus means that the receiving reference must be of this type as well. Not using OO is a quite stupid decision by the way ... its 4-20 times slower than the OO one because the integer stuff isn't optimized as it is mostly in for compatibility and simpler "get into" for switchers from old Blitz. |
| ||
| How about it BRL? Next iteration, could we have searchable documentation? |
| ||
| I agree. I'm going to wait till more tuts and better manual before I try Max again.Or till I hit a limit in Plus. mudcat |
| ||
| My main thing is sometimes ~why~ to use a given command - what is it good for? I'd be glad to add my own, few (lame/weak) examples of how things work if there were a central, "official" place. That is, good examples of how things "really work" to get things done (my own mediocre example is here). I had no trouble learning Blitz3D. I think that was in no small part due to its relatively comprehensive docs. But I agree - the BliitzMax docs could use some work (you can find what you need, but it's tougher than it should ideally be). |
| ||
| I'd be glad to add my own, few (lame/weak) examples of how things work if there were a central, "official" place. www.blitzwiki.org |
| ||
| ^ Aye.... I should better add there than nowhere (and now I plan to). But still... "official" (IDE-based / Blitz-site web-based).... Perhaps Off-Topic: Maybe you (or someone else knowledgeable) could help me fix my first BlitzWiki entry. My code is only partially formatted as code: http://www.blitzwiki.org/index.php/Menu How can I get it all formatted as code (sorry if this is something elementary - I'm not too familiar with Wikis). |
| ||
| I think the Wiki is a great community effort. You guys are doing an excellent job. But! It shouldn't be up to the users of the product to write the documentation for the manufacturers. Atleast without *some* kind of compensation. BMax is a good strong language with lots of promise, but it's weakest point right now is the documentation. I think it's great that we can explore the source code for most modules, but what if we don't have time to sift through the source code to see if a command is the specific command we're looking for. Before adding *any* new features, I think BRL should focus on the documentation. |
| ||
| but what if we don't have time to sift through the source code ... or don't have the programming skill to follow it. If BRL are expecting the source code to backfill the doc (there is no evidence that they are) then the source would have to be commented. The Wiki *is* good but I want the information at my fingertips just to 'F1's away. |
| ||
| It shouldn't be up to the users of the product to write the documentation for the manufacturers Well, you're right. But I've frequently observed that docs are remarkably often the weak point of otherwise-outstanding apps (not meant as absolution - just as an observation). The early comments on BlitzMax from Mark and/or Simon indicated that the docs might be a weak spot - and they are. I've noticed in my own minor doc-writing efforts that creating good docs is tough; I can only imagine what it's like for a whole language. But, that said, better docs would indeed help. I use the Wiki as well as these forums, but is there any path for the wiki/the forum knowledge to be integrated into the "official" BM docs? If not, it there a better way for users to submit docs for integration? |
| ||
| Documentation can be a problem. Escpecially for new languages that are still being developed. I love BMax. I haven't even opened up B3D or B+ since I bought BMax. You'll never be able to please all the people all of the time. Some programmers will pick up on certain aspects faster than others (that's life). I've got two weeks vacation comming up next week. I might take a crack at better understanding everything by sifting through the module sources. |
| ||
| That was my problem with wikipedia too, in Blitz 3D I can just hit F1 twice, with wiki I have to open a browser type in the url and then search for the command I need. That does sound very lazy but if you think of all the times you will have to do that initially to learn Blitz MAX then that adds up to a lot of time wasted. Wikipaedia is also currently not worth the effort anyway as every timesI’ve used it it's been a exact copy of MAX's default documentation. |
| ||
| WendellM: I fixed your code, all you have to do is place your code between the tags <pre> and </pre> Or you could also add a space before each and every line of code (including line breaks) to do it. |
   |