Hi Appcelerator team
Documentation is looking better but I feel it is missing some of the basics. Let me take a simple example of the Filesystem.
I am watching the professional 200 training series video, and even on that session, the trainer does not know which directory should be used. After many minutes of discussion, the team seemed to conclude that data should be stored in applicationDataDirectory.
On the simulator you can write to resourcesDirectory but it seems you can't in production as it is part of the signed application - well maybe?
The point is, the documentation in the API says:
"resourcesDirectory string readonly constant where your application resources are located"
The documentation tells us WHAT the thing is, but not WHAT it is for.
How to improve:
- Documentation should say why to use something, not be a bland list of data types.
- Each of the classes, should have real examples (Filesystem should have a an example of reading and writing to a file).
- Examples should be at the top
Look at CPAN (search.cpan.org) and modules have a Title, Synopsis and Description first, then the list of methods.
The best thing is, all the examples are already written, inside KitchenSync, the content just needs to be moved into the APIs.
Keep up the good work and continue to improve the docs.
Further documentation bugs: Filesystem talks about Titanium.Filesystem.File, but doesn't list it as an object, but does reference it in the text of getFile et al. Clicking https://developer.appcelerator.com/apidoc/mobile/1.3/Titanium.Filesystem.File.html returns a 404 - missing file.
Having dug deep this could partially answer my question as why I can't download an image from a webserver and write it to a folder inside my apps Resources directory on an actual device. And yes, you can in Simulator!
As Scott points out (on this admittedly old thread) documentation which would take us gently by the hand and lead us through the where's and the why's would be very useful indeed.