I hope it's not to late, I will try to give you a honest answer.
On the first glance jQuery Mobile documentation looks like hell, chaotic bunch of ambiguous data.
- A lot of information without a real context. This documentation is written for developers with prior jQuery knowledge. If you carefully take a look you will see that basic documentation form reflects jQuery documentation. Basically it is useful only if you know what and where to look.
- On the other side, once you learn what's what it becomes obviously easy to read.
- There are a lot of mistakes and it takes to much time for them to get corrected. This is partially fixed thanks to StackOverflow, here you will more answers (better explained) and information regarding jQuery Mobile then provided in official documentation.
- I don't know what happened to 1.4 documentation, 1.3 had much better one. You would learn everything from DEMO site and API site will only give you better perspective.
- Don't worry about deprecated methods, jQuery Mobile 1.5 will have all needed answers. Old documentation rarely has information about future software releases (I'm not talking here only about jQuery Mobile, it is always like that). When few years ago development started on jQuery Mobile, plan was created six versions in advance, you can still find it online.
- jQuery Mobile developers don't have that much resources like jQuery developers, plus everything is done on pro bono basis. Free product are tied to certain limitations, in this case documentation pulled the shortest straw.
- While jQuery Mobile don't have best documentation ever it has best 3rd party support, other mobile frameworks don't come close, except maybe Sencha Touch but that's completely different story.
- Also, when you find an error just report it on their github page. It will be fixed in notime, plus support is free ;)
Regarding your second question .jqmData() is a method while :jqmData( is a selector. But you are correct, method .jqmData( accepts parameters so it's a documentation mistake.
Regarding your third question, use of data-* attributes is a right development strategy but ultimately not the only one, you can use anything you like. Don't forget sometimes it is not easy to be HTML developer in HTML5 world.
If you are still not certain regarding jQuery Mobile then take a look at my article covering currently best known frameworks. These are oldest and best known frameworks, all of them are still in development and they are more then stable.
My advice would be these three frameworks:
- Sencha Touch
- Kendo UI (PhoneJS as an alternative)
- jQuery Mobile
Several newer frameworks like Famo.us advertise themselves like second coming so you can also look at them. Just be careful newer is far from better.
If you have more questions feel free to ask, I have more then enough experience with mobile world, specially with jQuery Mobile.