update the Resources/API page to include changes from 2012

Solar2D Daily Builds and Public Releases
#1

Corona,

As a paying customer, I’m really pained by how out of date the Resources/API document page is. Its getting to be very difficult to work in Corona without proper documentation.

you don’t even have the Image Sheet / Image Group stuff up yet, and the only place to read how its used is to look at the blog, and then hunt in the forums to find out about the setFrame API.

Please PLEASE get the documentation up to speed, as its slowing down our development and it not professional to do this to paying customers.

-Aaron
[import]uid: 122310 topic_id: 26151 reply_id: 326151[/import]

#2

If you’ve read the blog/news at all over the last few months you’d see that an updated docs system is on the way over at Ansca HQ. But clearly they have a lot of fish to fry at the moment, so it’s in the bucket with various other things that get posts like this. :slight_smile:

EDIT: Here’s Walter talking about the Documentation update. [import]uid: 41884 topic_id: 26151 reply_id: 105901[/import]

#3

@richard9: yes, I’m aware that there has been lots of TALK about updating the documentation, but that doesn’t change the fact that I wasted a lot of time trying to figure out how to use the image sheet api since it was not documented.

This is not an open source free project…I pay them $300+ a year, and I expect that the framework would be documented. Not someday in the future, but NOW. The post you referenced is a month old!

When they release a new feature, part of the process should be to document it. If that means we get 1 less feature, fine…at least I’ll know it exists and how to use it.

Anyway, I figure unless people are vocal about the things they need, stuff will just never get fixed or released. My point is that is very bad form to not have up-to-date documentation, and its essential that this is pushed out today, not several months from now.

[import]uid: 122310 topic_id: 26151 reply_id: 105905[/import]

#4

Corona’s documentation is many times better then a lot of other platforms/frameworks I’ve used, both in terms of games and “sensible” software.

I would say that imageSheets haven’t made it to the stable build yet and are still under testing, so I can understand why there’s no documentation at this stage.

Although I agree that documentation is a constant gripe, remember it’s not just Ansca, as I said they’re one of the better offerings about.

Besides it’s not really that much hassle is it? Have a quick look around the blog, google things (to make up for the crappy Ansca search functionality :slight_smile: ) and remember the best way to learn is just to dig around yourself. [import]uid: 33275 topic_id: 26151 reply_id: 105908[/import]

#5

Yes, you did right to request here. I’ve seen carbon copies of your post for things like audio/network/bugfix feature x, so I’m sure it’s just going into the priority queue like everything else. You don’t rearchitect bugtracking+doc systems in a day so I’m not surprised things are getting stretched out a bit.

Anyway, the bottom line is that it’s a small startup that needs to be agile while it gets stuff done. So you’re going to see features rush out from time to time. It’s the nature of the daily build process (as opposed to stable builds where the details are all explained and tested in detail). I imagine their new system will speed up the documentation cycle a bit.

Maybe Danny can speak up when he has some time as to status. *shrug* [import]uid: 41884 topic_id: 26151 reply_id: 105912[/import]

#6

I envy you the amount of spare time you have to waste on digging around for things you need right now. I assume the team waiting for you to finish your task is standing behind cheering your google skills :wink:

For something that is pushed as much as image sheets are, they have almost no documentation at all. There were several changes to the apis in recent builds, which are not documented. For example sprite trimming was added - but how to use it? [import]uid: 109453 topic_id: 26151 reply_id: 105913[/import]

#7

Quick Google search revealed some people talking about this - it seems as though they’ve updated the Horse Animation sample app and that looks as though it contains trimmed frames using the image sheet API.

Haven’t looked into it too much, but it might be worth checking… [import]uid: 33275 topic_id: 26151 reply_id: 105917[/import]

#8

@SegaBoy - I run a professional game studio…I make a living by writing and publishing games, not by hunting for API usage that is scattered around the website (and you have to do different types of searches since the search boxes for the forums is different from the search boxes for the blog). Just because others do it worse than Corona doesn’t mean that Corona does it well. If your job is making a framework, part of your job is documenting the framework.

@richard9 - I’m not asking for them to rearchitect their documentation system…I’m asking them to document the existing API. If they want to waste their time putting up a new system, thats up to them…i just want the API that exists in the latest daily build, that I PAY for, to be documented! Even just a few sentences saying what the functions are and their parameter names would be a huge step i the right direction…just put up a stub sheet for each function, and let customers do the documentation for you…just don’t put up nothing! [import]uid: 122310 topic_id: 26151 reply_id: 105918[/import]

#9

I don’t disagree aisaken, all I’m saying is that documentation (or lack of) is a problem for many frameworks - try checking out Magento, one of the world’ largest e-commerce framework and you’ll soon appreciate what Ansca offers :slight_smile:

I completely agree about the search functionality, which is why I always use the google search specified to the ansca domain (site:anscamobile.com ‘search term’) as I find that much, much easier.

I do however think that until an API becomes available in the general build, then Ansca is still working on that API and isn’t ready to finalise documentation.

One thing it does do is build up the sense of community, there’s a number of people here that are readily available to offer there help on such matters - and again in this department Ansca is lies better then many other frameworks I’ve used, [import]uid: 33275 topic_id: 26151 reply_id: 105919[/import]

#10

@SegaBoy - thanks for the tip on the google search…great idea and very useful

I agree with you about the community…thats why I suggest they just put up a stub page for every function which simply lists the function name and parameters, and the community could fill in the details in the comments section. That would be a huge step forward, and would be an afternoon of work on Ansca’s part…this way at least I have one place to go when search to see what functions exist.

Great thread everyone…now we have an actionable solution that would be very easy for Ansca to implement today. [import]uid: 122310 topic_id: 26151 reply_id: 105920[/import]

#11

Hey guys,

RE Search; We’re working on the search - it’s terrible and we do have plans for a revamp of it very soon.

RE Docs; It isn’t just “TALK”, it is something that a good amount of time has gone into and hopefully will soon be ready to put out there.

SegaBoy was correct regarding docs and dailies - we do not edit the API pages for features we’re still testing and changing and trying to get just right before the next stable release.

Daily builds let you have a play around before we release new stuff, learn about it, read the blogs associated if you want extra info, etc - but we can’t update docs every day for whatever changes are being made behind the scenes.

EDIT: Update - I’ve just checked and the new update of the API pages (hundreds upon hundreds of them) is 48.25% complete :wink: [import]uid: 52491 topic_id: 26151 reply_id: 106001[/import]

#12

Actually, it’s 317 Jiga-pages. Great Scott!!! (quoting from Back to the Future)

And that means we’re 48.2537294% done to be precise :smiley:
[import]uid: 26 topic_id: 26151 reply_id: 106003[/import]

#13

@Peach & @Walter ,

I really thank you both for updating us about the CoronaSDK Docs!

Sure you have an idea of how important it is for us - the developers to go into when trying to develop something else better than and that is not exactly “all into our mind” decorated. :wink:

Thanks,
Rodrigo. [import]uid: 89165 topic_id: 26151 reply_id: 106005[/import]

#14

@peach, @walter - thank you for the update. What is the velocity? How many % are you getting done per day?

I totally get that its difficult to provide detailed documentation for every function as things are in flux, but I its not that hard to make the developer who checks in a new API function to write a 400 character description of the function and the parameters it uses.

All i’m asking for is an up to date list of all the functions you provide, and the parameters each of those functions takes in…the community can document the rest as needed…

Also, once this task is complete, will the new API docs stay in sync? or will they once again get out of date waiting for the next cycle of doc updates? [import]uid: 122310 topic_id: 26151 reply_id: 106017[/import]

#15

The new system will stay up to date, it’s just as important to us as it is to you, thats why it’s taking a while because we want it done right.

Thanks [import]uid: 84637 topic_id: 26151 reply_id: 106085[/import]