The unprofessionality of CC's Lua APIs and wiki

Hello.
I'm sure that some CC users that were programmers have had problems with using the APIs, learning about ComputerCraft's mechanisms and a lot of more things. You don't event have to have any programmer experience to notice that, for example, the official Lua wiki offers much more detailed information than CC's one, every library, every function is precisely described. I even wondered what articles' authors think when they write them:

Hahaha, f**k me and my life, let's write this s**t in 5 minutes and others will think I'm genius! Oh, and I better don't forget to write my nick, so I'm sure that anybody who will read this will know who to be grateful!

Now let's talk about the APIs. Maybe not everybody experienced it, but when it comes to precisely operating with items or handling multiple events in little time, just when the computers are the best solutions, the defects of core come to light. And example:

---

If function turtle.drop() would drop a single item from a stack, the code to filter a single item (really?) would look like that:

turtle.drop()

And the code to drop a whole stack would look like this:

for i = 1, 64 do
turtle.drop()
end

Meanwhile, the drop() function drops a whole stack, so it's one line of code, but the machine that filters one item looks like this:

Spoiler

And it wouldn't be possible without the BuildCraft mod. Imagine a machine that operates with hundreds of stacks of items, f.e. on a SMP server. Additionaly, it's just its stack splitter.

---

So, that was just a quick example of one of a plenty of functions with ill-considered solutions. I bet a big corporation such as Microsoft would think twice before creating a core function in their language or API.
In my opinion, the best thing that CC's author would do in next update is nothing else than updating core functions, even if it would crash some of the programs written before. As for the wiki, there should be group assebled that will be its admins and first of all, redactors. What do you think, people?

Urgh, the overall wiki removal isn't bad idea through…

Well, what I think:

I'm sure that some CC users that were programmers have had problems with using the APIs, learning about ComputerCraft's mechanisms and a lot of more things.

If you have problems learning or using the APIs or something, you are not a good programmer, there's plenty information out there about lua and there's a lot of tutorials in this forum (I never went to the wiki). I learned lua (never used it before) and CC APIs just in a day, with no problems.

Now let's talk about the APIs. Maybe not everybody experienced it, but when it comes to precisely operating with items or handling multiple events in little time, just when the computers are the best solutions, the defects of core come to light.

Suggestions are always welcome to improve the mod, if you really think it's so bad, then go make one yourself if it's so easy.

As for the wiki, there should be group assebled that will be its admins and first of all, redactors.

I agree that there should be some improvements on the wiki, but you could just make a suggestion instead of writing a post like this.
It's easy to criticize, try helping a little instead.

there's plenty information out there about lua and there's a lot of tutorials in this forum (I never went to the wiki). I learned lua (never used it before) and CC APIs just in a day, with no problems.

I don't say there's not enough information and I can't learn APIs, but still, in some cases, the user must guess what the specific function do only by it's name, and possibly test it in the interactive lua console.

As for my… "laziness", not helping - Sorry, but i don't think I can do much about things I would like to change. The bad design of functions is a problem that cannot be easly solved by one man, so I think it would be better to discuss it in this forum, instead of just posting a suggestion (which, as everybody know, won't be ever read by CC's staff).

I might not be a "staff" because Dan200 is the only one that "codes" the mod officially, but I definitely read every suggestion/bug thread and about 90% of other threads.

I do see your issue with the turtle.drop() command, and how it drops a whole stack instead of a single item. I personally would say this is BETTER than dropping a single item, but thats just my opinion.

As for the "documentation" itself, the wiki is worked on by a handful of people every now and then, it definitely does have some good information, and ONE DAY maybe I'll help them out as well (even though I dread wiki so much).

CC is not a "user" friendly mod, it's never been planned to be. It's a CODERS mod, therefor as most coders know, not everything in a language does exactly what you expect it to and sometimes that leads to trial and error.

If there is any other suggestions/concerns/comments definitely feel free to post them in the suggestions forum or in general as well. My staff and myself is here to help you and listen to you, just because someone doesn't always make a reply, doesn't mean your thread isn't heard :mellow:/>/>

Any good suggestions/comments/concerns get forwarded to Dan200 by my automatically, so fret not, he sees them too.

Furthermore, Lua is a real programming language. Mainly used for scripting.

Being new to programming, scripting and CC I can say that the wiki is lacking. I think it needs a lot of fleshing out. Even just small comments about how rs.setBundledOutput() would set just what you specify and set the others to false would help quite a lot.

That being said, would I have gotten this far without the wiki? Hell no. I owe the existence of my program to that wiki and I am really glad someone took their time to actually write anything on it.

Yeah, the site has only really been public for less than a month… so a full fledged wiki is personally imo a ways off until someone really sat down and worked on for like 5 hours straight lol.

that and there isn't much to wiki yet. the mod has like what 4 blocks.

passinglurker, on 11 March 2012 - 04:04 AM said:

that and there isn't much to wiki yet. the mod has like what 4 blocks.

4 types of turtles, computer, diskdrive, and modem. I'd say 7.

CC is not a "user" friendly mod, it's never been planned to be. It's a CODERS mod, therefor as most coders know, not everything in a language does exactly what you expect it to and sometimes that leads to trial and error.

Yeah, in this mod the user is actually a coder, and he/she would also like to know what do the functions do, which is a task for the wiki :I OR, if you mean that CC functions aren't planned to be described, then ok, I don't have more questions.

Please understand what I mean: At this moment, there are some problems with functions' structure, but still everything I'd want to code is possible. I only want to talk about those problems and think how can be they solved. I gave an example with turtle.drop(), which cleary shows that there should be a better solution, and it would be good both if you want to drop a full stack and a single item. Still, a number of functions need improvement, I can't just post a thread in Suggestions with full list of ideas and hope I won't be ridiculed.

You won't be ridiculed, you might get answers that you don't like… but if anyone outright flames you, I'll handle it. More suggestions aren't a bad thing ever.

I agree that there are certain points that can and probably should be improved in the long run.
But then again you have to keep in mind that CC is developed by one person who does this for free in his spare time.

Making documentation is never a fun job and it takes both time and effort to do it. Time which would keep Dan away from concentrating on coding. :mellow:/>/>
Also a wiki is a work of collaberation. We, the users, should fill in the information of the wiki. Not (necessarily) the creators!

If you're active in the CC community, then you're bound to know what the functions do and what they return pretty quickly.
So if anyone learns something about CC functions, then they are encouraged to write them down in the wiki.
But you can't rightfully expect anyone to do it, because it isn't anybody's paid job to do so.

If I'll have some time and don't have other interesting things to do, then I might add to the wiki some day.
Since I haven't even used it yet though, adding to it isn't a particularly satisfying endeavor I feel inclined to do at the moment.
The same thing might be true for most other people who could and would add something, if not for the lack of interest and/or energy.

Of course, I don't order or force anyone to work now, I just point out other people that something is wrong.

If you're active in the CC community, then you're bound to know what the functions do and what they return pretty quickly.

In fact, I'm pretty active, but still I think that if wiki was fledged, it would be a better source of informations.

Intelligent remark, btw.

Jajnick, on 11 March 2012 - 02:38 PM said:

In fact, I'm pretty active, but still I think that if wiki was fledged, it would be a better source of informations.

Alright, that's a totally valid opinion.
But when you say active, does that include the wiki? Are you adding content to the wiki?
If not, then what's holding you back filling the wiki with content yourself?

Casper7526, on 11 March 2012 - 02:16 AM said:

I do see your issue with the turtle.drop() command, and how it drops a whole stack instead of a single item. I personally would say this is BETTER than dropping a single item, but thats just my opinion.

It is definitely WHORSE because turtle UNABLE other behavior.
One by one whole stack can be dropped, but not otherwise.
Ask Dan200 to repair situation by adding optional arguments like this:

result = turtle.drop( [ quantity, [ slot] ] )
--if quantity == nil, full stack dropped;
--if slot == nil, current slot used;
--result is a quantity of items dropped because it can be less than you ask.

This way no old programs breaks, turtle.drop(1) can be used to drop 1 item, all will be happy.

Suggestion

Casper7526, on 11 March 2012 - 02:16 AM said:

I do see your issue with the turtle.drop() command, and how it drops a whole stack instead of a single item. I personally would say this is BETTER than dropping a single item, but thats just my opinion.

Why not simply add argument to this function? It will then drop specified amount of items (or whole stack if no argument given). And EVERYONE will be HAPPY :mellow:/>/> And it's not much work do do that.
Oops… Slowpoke… ;)/>/>

Well what if we instead of wasting our time here complaining, just go to the wiki and make it how we want it to be?

I've started a mission to systematically attack all the APIs, making a clean API page for the API as a whole plus a decent function page for each function within it. I've done Bit and Color and still have the rest left.

Jajnick, on 10 March 2012 - 10:01 PM said:

Hello.
I'm sure that some CC users that were programmers have had problems with using the APIs, learning about ComputerCraft's mechanisms and a lot of more things. You don't event have to have any programmer experience to notice that, for example, the official Lua wiki offers much more detailed information than CC's one, every library, every function is precisely described. I even wondered what articles' authors think when they write them:

Hahaha, f**k me and my life, let's write this s**t in 5 minutes and others will think I'm genius! Oh, and I better don't forget to write my nick, so I'm sure that anybody who will read this will know who to be grateful!

Now let's talk about the APIs. Maybe not everybody experienced it, but when it comes to precisely operating with items or handling multiple events in little time, just when the computers are the best solutions, the defects of core come to light. And example:

---

If function turtle.drop() would drop a single item from a stack, the code to filter a single item (really?) would look like that:

turtle.drop()

And the code to drop a whole stack would look like this:

for i = 1, 64 do
turtle.drop()
end

Meanwhile, the drop() function drops a whole stack, so it's one line of code, but the machine that filters one item looks like this:

Spoiler

And it wouldn't be possible without the BuildCraft mod. Imagine a machine that operates with hundreds of stacks of items, f.e. on a SMP server. Additionaly, it's just its stack splitter.

---

So, that was just a quick example of one of a plenty of functions with ill-considered solutions. I bet a big corporation such as Microsoft would think twice before creating a core function in their language or API.
In my opinion, the best thing that CC's author would do in next update is nothing else than updating core functions, even if it would crash some of the programs written before. As for the wiki, there should be group assebled that will be its admins and first of all, redactors. What do you think, people?

Urgh, the overall wiki removal isn't bad idea through…

I have started a group dedicated to working on and maintaining the wiki, check out my post about CCCFU. Sign up and help out!

Thank you. :mellow:/>/>
If I'll find some free time I'll help, at least the wiki will be finally useful.

Jajnick, on 14 March 2012 - 10:12 PM said:

Thank you. :D/>/>
If I'll find some free time I'll help, at least the wiki will be finally useful.

Make sure to apply on our thread!

Casper7526, on 11 March 2012 - 02:16 AM said:

I do see your issue with the turtle.drop() command, and how it drops a whole stack instead of a single item. I personally would say this is BETTER than dropping a single item, but thats just my opinion.

There's a workaround. Get Pfaeff's Allocator. It ejects only a single item at a time, from a stack.

CC is not a "user" friendly mod, it's never been planned to be. It's a CODERS mod

Granted, but Lua is easily the most simplistic language I've ever come across. If Dan200 had decided to use Lisp as the scripting language, then we might have something to genuinely complain about. :D/>/>

petrus4, on 15 March 2012 - 06:00 AM said:

Casper7526, on 11 March 2012 - 02:16 AM said:

I do see your issue with the turtle.drop() command, and how it drops a whole stack instead of a single item. I personally would say this is BETTER than dropping a single item, but thats just my opinion.

There's a workaround. Get Pfaeff's Allocator. It ejects only a single item at a time, from a stack.

That's no longer necessary. The new version of CC now supports dropping different quantities of blocks:

turtle.drop( quantity )