Talk:Functions
From Spheriki
Contents |
Function Pages
- Should function pages be named by function only or by object.function? For instance, should a page be called blit or Image.blit (as it is at the moment.) Of course, choosing object.function would offer a quick way of observing what that function means but will ruin alphabetic order on Functions. --BGenesis 13:10, 16 June 2006 (PDT)
- Well, what about both? First there's object.function() as the source page, the articles to function() without object. in front of it should REDIRECT to the object.function page. Except when they're different of course, like the difference between SetColorMask() and font.setColorMask(). --DaVince 14:07, 16 June 2006 (PDT)
- That could be done, I suppose. It's up to the function creator then, or anyone on the Sphere Documentation Project to do all at once. --BGenesis 14:54, 16 June 2006 (PDT)
- The functions should be organized by section like in the doc_functions file. So image.blit(x,y), etc. will be together on the main functions page. As well, image.blit() should only be used, otherwise it will be redundant and just take up space.--Beaker
- That's a nice idea, Beaker. Unfortunately, it can't be done without a custom Functions page that is manually maintained. You can do that, I suppose. It's an interesting decision. Should we have a Functions page rather than having it direct to Category:Functions? --BGenesis 14:53, 16 June 2006 (PDT)
- Yes, these things have to be organized, otherwise it's going to be terrible to navigate through. Each page can be seperate, even as it is now, but there has to be a main functions page that has things organized according to what the functions do.--Beaker
- No, I made a few redirects but they aren't added to the category. --DaVince 15:11, 16 June 2006 (PDT)
- Using 'void' would be both redundant and misleading: JS doesn't have have it, and it alludes to C and C++, which is irrelevant in the context of using Sphere. --Tunginobi 02:33, 19 June 2006 (PDT)
- Is it ok to give up 'function' as a data type? It seems kinda logical and not confusing for newbies...--DaVince 13:55, 19 June 2006 (PDT)
Decision
Right, instead of making Functions redirect to Category:Functions, we'll do this:
- Functions will be a manually maintained page that lists functions in groups depending on what they do.
- Function docs will be in a page called Object.function and will also have a redirect page at function unless, of course, the function on its own is something different (as in SetColorMask).
- Only the latter redirect pages will be listed in Category:Function
Seeing as Beaker just kicked ass and has done it so very nicely for us, we'll use his page. I don't think the above needs to be applied now.
--BGenesis 08:09, 17 June 2006 (PDT)
Only one problem, Beaker. I don't think we should have the ()s and the arguments in the function page name. --BGenesis
I'm leaning towards having functions listed alphabetically, and having them listed by category/object/whatever, essentially having two index pages.
Here's an example of something I think was done right: FBWiki. Scroll down the left column, to the Language section. The Alphabetical Keyword List and Functional Keyword List kinda have what I've got in mind. --Tunginobi 04:00, 19 June 2006 (PDT)
Temporary though it may be, I just went ahead and cleaned up virtually all the potential function page links in Beaker's big list of functions. All objects, right down to the SpritesetBase and Rectangle used by SetClippingRectangle() and GetClippingRectangle(), are ready to roll. Just click a red link and edit to your heart's content! --Tunginobi 04:50, 20 June 2006 (PDT)
[code] or no [code]?
I noticed some of the function articles have the [code] tag. I personally don't think this looks better than typing the function's name without the [code] tags.
It looks like this, which might be useful for certain things, but it's used in 'see also' sections and whenever the function name is used.
What do others think about this? --DaVince 00:19, 20 June 2006 (PDT)
- The code tag is useful to distinguish program identifiers from regular text. As for the 'see also' section and the like, I don't think it's needed, but that could change if 'see also' happens to contain links that are just link labels. --Tunginobi 02:12, 20 June 2006 (PDT)
Object Pages - The 'Object-' prefix
I've noticed a few pages directly linking to object pages using their names, such as Color. However, Beaker says "Also, objects themselves should have a page corresponding to that object, something like Object-Image should be used to distinguish it from a function". I've been going by Beaker's word, I've only been using it for links so far, no pages yet. I've also got a link to a Rectangle, used by the GetClippingRectangle(). Which one are we using? --Tunginobi 01:07, 21 June 2006 (PDT)
'See also' section
Needs some conventions. Do we only list functions that are directly linked to the function? Do we also link functions that are used in the examples? What about related topics? Do we include parameters after the function links in the parentheses? It looks rather awkward.
My current convention is to first list all related functions in alphabetical order, without any parameters. Then a spare blank line. A new list then contains related topics, objects and external reference links in alphabetical order. I don't list functions used only in the examples at the moment. --Tunginobi 06:08, 21 June 2006 (PDT)
- I'm including all other functions in it that are in the article, based on importancy. First the ones closest and most related functions at the top, and the example functions last. I always add a () behind it when appropiate, but no more.
- Listing the functions in the examples would be useful, because someone would be wondering what that function was and has an easy click-through available to it then. --DaVince 06:40, 21 June 2006 (PDT)
Old Intro
Being placed here for those who still wish to refer to it. --Tunginobi 05:15, 12 July 2006 (PDT)
- This is a general outline of the functions given from the doc_functions.txt file. When adding a new function, please either use the linked page here, or change it to your page name. As well, please remove the description of the function given after the link here (for now they are just there for your reference when making a new page).
- Naming conventions should also be used when making new pages regarding the function arguments. Discuss on this article's talk page. As well, the ordering could use some work.
- Also, objects themselves should have a page corresponding to that object, something like Object-Image should be used to distinguish it from a function, and Image(Object) should be avoided as to not confuse the reader about the existence of a function called "Image."
- Finally, properties/members of objects don't need their own page, despite what is done here. For example, animation_object.width and animation_object.height should be grouped together on the animation_object page, and explained there, while the functions of animation_object have their own page, but are listed there. See the template in the functions category.
- When the documentation is complete, please remove this preface and insert a more user friendly one.--Beaker 06:41, 17 June 2006 (PDT)
Total restructure
I categorised the functions under an extra level of headings. I put the map engine functions in a new section outside of Sphere objects, because it swamps the rest of the stuff there.
Mainly, I hope this help newbies, who want to read through the functions, just to see what Sphere is capable of. The function signatures and summaries should also be useful to veterans. Anybody who wants the alphabetical list still has the wiki index page. --Tunginobi 01:55, 31 January 2007 (GMT)
3D Functions section
I've removed it, since they only belong to an unofficial branch of Sphere by Beaker. The main engine doesn't feature those functions. --Tunginobi 01:01, 4 December 2007 (GMT)
