[Suggestion] Term, Monitor and Window APIs

As we all know monitor and window APIs' functions are currently in Term API page. It may be confusing or even hard to find for new users if they would be looking for monitor and window API specific functions. I would suggest to remove those functions from Term API and place them in their appropriate pages: move monitor.setTextScale to Monitor page and all window API functions to Window API page. Of course it would be mentioned that monitors and windows support all Term API functions and there would be a link to Term API. What do you think?

From where I'm sitting, "window" and "monitor" objects are both "terminal" objects. It makes sense to me to have one page which lists all the functions available to terminal objects in one place, and I believe the current version of the Term API article makes it very clear which functions are available to which of those objects.

That's just my view, of course - it's no big deal to me how the layout works. It just seems fine to me as it is.

Bomb Bloke, on 06 April 2014 - 12:53 PM said:

From where I'm sitting, "window" and "monitor" objects are both "terminal" objects. It makes sense to me to have one page which lists all the functions available to terminal objects in one place…

Totally agreed. But I think it would be more reasonable to put them in the appropriate page (although, Monitor page is more about the block than an API). But I do agree with you.

For everyone on the Forums, don't be shy, write what you would like. I may even make a poll, it makes sense to ask the community what would suit them the best.

MKlegoman357, on 06 April 2014 - 07:17 PM said:

(although, Monitor page is more about the block than an API).

There was a monitor API page, but it was deleted on the grounds that the term API page made it redundant. Going through with this would require it to be put back in place.

By the way, what's with the call to put explanations / examples on the API pages? What's wrong with the ones on the function pages?

Bomb Bloke, on 06 April 2014 - 11:25 PM said:

By the way, what's with the call to put explanations / examples on the API pages? What's wrong with the ones on the function pages?

Parallel API should be explained a little bit more, because 'Parallel is an API which allows you to multitask.' is not very informative on how it works. Maybe the explanation about how the parallel API works should be moved from the functions explanations to the actual parallel page because it describes how multitasking in ComputerCraft works. And for the Window API, it would be nice to have it explained, how it works, how is it useful and some examples would be good too.

Also, when looking at the pages I try to see what people new to ComputerCraft see, what I saw when I was new to CC and parallel API was one of the APIs I understood only when someone asked about it on Ask a Pro. I actually saw many people asking about it and complaining about the page that it isn't informative enough. When I looked at the Window API for the first time and saw it's explanation it was just asking for examples. Of course, the word 'window' already says what it is but still, some more explanation would be nice.

Truth be told I do intend to flesh out the explanation of the window API… once I've actually played with it enough to fully understand the exact quirks of its functions… still dunno what it can / cannot do.

That page just doesn't seem like the place for examples (to me), but see what you make of it once I get around to updating it. I'm assuming here that no one will beat me to it. ;)/>/>

I'm kinda toying with the idea of making an article based around "terminal objects" and moving all shared term/window/monitor functions into that. Yeah yeah, sounds crazy, and it'd involve a bit more re-organization than I'd like… Odds are I'll talk myself out of that idea (or, rather more likely again, not bother with it either way).

It would be good to have an example somewhere as to how scripters can build their own terminal objects, eg, a simple aggregate device that renders to all attached monitors at once for eg.

One thing I really want to do is start putting together navigation templates. They're sorely needed, as you can only get so far with potholes and the like.

Bomb Bloke, on 07 April 2014 - 12:06 PM said:

I'm kinda toying with the idea of making an article based around "terminal objects" and moving all shared term/window/monitor functions into that. Yeah yeah, sounds crazy, and it'd involve a bit more re-organization than I'd like… Odds are I'll talk myself out of that idea (or, rather more likely again, not bother with it either way).

It would be good to have an example somewhere as to how scripters can build their own terminal objects, eg, a simple aggregate device that renders to all attached monitors at once for eg.

I was thinking the same thing, word to word, really.

Bomb Bloke, on 07 April 2014 - 12:06 PM said:

I'm assuming here that no one will beat me to it. ;)/>

Don't be so sure :P/>

Also, I was thinking to create a new variable for {{API table}} tag which would format the table to be used by peripherals, like printer API. I thought that maybe the method could be formatted something like this: printer.newPage() - the word 'printer' would be italic as there is no actual 'printer API'. I still haven't decided how would that variable work. I have two versions for now:

1. 
   {{API table|Printer|image=Grid disk.png|type=peripheral|2=
   
   {{API table/row
   |printer.newPage()}}
   
   }}
   

2. 
   {{API table|Printer|image=Grid disk.png|type=printer|2=
   
   {{API table/row
   |newPage() <-- no need for 'printer.' part, it's added automatically making 'printer' italic.
   }}
   
   }}
   

For the second example, still haven't found a way to easily implement links. Maybe only 'newPage()' should be linked but that may look a little strange: printer.newPage()

I'm afraid I can't see a method of passing the "type" value from the "API table" template to the "API table/row" template that wouldn't make them rather painful to use.

Perhaps sandbox what you've got and I'll see what I can make of it.

Oh, right, forgot about {{API table/row}}. Well, my main idea was to use one template for both, API functions and peripheral methods. Remember:

Peripheral functions are called methods, a term borrowed from Java.

As we already have a table template all we would need is an easy way to change the word 'Function' to 'Method' (because of the Golden Rule written above). Is there an easy way to pass a variable to a template without giving it a value, so instead of something like 'type=peripheral' we could just use 'peripheral' (but this wouldn't work, or would it O_O?). And for the links, it could be made easily enough by hand:

[[printer.newPage|''printer''.newPage]]()

EDIT: hmm, or maybe just optional arguments for all of the three words which are in the table? 3 - for naming the first column, 4 - for naming the second column and 5 - for third.

{{API table|Printer|image=Grid disk.png|3=Method|2=

{{API table/row
|printer.newPage()}}

}}

Eeeehhhhh I'm inclined to take that "golden rule" as "opinion", and even perhaps to strike it from the source page. Run "type" on 'em and see what name that gives you. ;)/>

That said, I'm not familiar enough with Lua to say whether or not "method" is a valid term for anything within the language.

I'm afraid I'm not aware of any method to pass a value to a template without assigning it a name of some sort. Optional arguments are simple though, something like this should do what you're thinking:

{{#if: {{{3|}}} | {{{3}}} | Function }}

Though you'd likely want to use something more descriptive than "3".

I think it sounds better even though they're just simple funct… But wait! They are functions added by a peripheral. Those functions are natively written in Java. Because a block in Minecraft is added by creating it's own class those functions are called methods, because functions in a class are(?) called methods.

Note that I have no Java experience at all and all of this may be wrong.

Maybe it could be named 'col1', 'col2' and 'col3'? Or 'colname1-3'. 'coltitle1-3'?

Also, could you explain to me how variables work? How they work in ifs and standalone. MediaWiki's documentation about certain things is hard to find.

{{{3|}}}

How is that different from this:

{{{3}}}

MKlegoman357, on 08 April 2014 - 01:54 PM said:

I think it sounds better even though they're just simple funct… But wait! They are functions added by a peripheral. Those functions are natively written in Java. Because a block in Minecraft is added by creating it's own class those functions are called methods, because functions in a class are(?) called methods.

Hah! I have to admit, it does make sense in a crazy kind of way, and that's probably pretty close to the reasoning Immibis was following. The functions do indeed belong to the peripheral.

I'd argue that it doesn't change the fact that the code's being executed via Lua's function calls, but it's getting pretty late here so I wouldn't argue very hard. ;)/>

MKlegoman357, on 08 April 2014 - 02:01 PM said:

Also, could you explain to me how variables work? How they work in ifs and standalone. MediaWiki's documentation about certain things is hard to find.

Here's the page you're after, at least, for that particular question. This page has a lot of other useful information on making templates react to parameters.

Thank you for that. Also, how about the idea of peripheral names in their pages being italic? If I do it I'll change all pages at once so I'm just asking if you do like this idea before I did that.

In the function names? Sure, I think it's a good idea.

Bomb Bloke, on 08 April 2014 - 11:29 PM said:

In the function names? Sure, I think it's a good idea.

Done :D/>

I have came up with another idea for function pages and their examples. I think it would be better if we would make the function, that the page is about, bold in examples so people could see it better?

{{Function
|name=term.clear()
|example={{Example
|desc=Clears the screen
|code='''term.clear()'''  <-- Here, make it bold
}}
}}

If you like, though it strikes me that'll lead to a whole lot of edits with little gain. I personally wouldn't bother unless I had something else to add to a given function page at the time.