View Issue Details

IDProjectCategoryView StatusLast Update
0018999MediaMonkey 5Extensions frameworkpublic2022-05-09 20:19
Reporterzvezdan Assigned To 
PriorityurgentSeverityminorReproducibilityN/A
Status resolvedResolutionreopened 
Product Version5.0.3 
Target Version5.0.4 
Summary0018999: API is unorganized, poorly documented, with many things missing or wrong
DescriptionJust one example on which I spent my time to discover why it is not working. The API says there is AddTracksAsync, while in fact it is addTracksAsync.
TagsNo tags attached.
Fixed in build

Relationships

related to 0018953 resolvedLudek Some COM methods not implemented 

Activities

drakinite

2022-04-24 04:59

developer   ~0067698

AddTracksAsync has been fixed a few days ago. Asked Jiri to update it on the site.

Please provide a list of methods whose documentation is inaccurate and I can fix them.

zvezdan

2022-04-24 06:04

updater   ~0067701

Why are you assigning this issue to me? I am not payed by Ventis Media to do your job.

There is not only thing with "inaccurate" methods. There is a bunch of methods, properties and events that are not mentioned in API at all. You have some of them already mentioned by me in https://www.ventismedia.com/mantis/view.php?id=18998.

And how could I know as a user what your "app" object contains of these methods/events internally that is not mentioned in API? And many other objects that are part of your binary files, like "player" and similar.

rusty

2022-04-25 20:23

administrator   ~0067778

Tagging as resolved since Jiri apparently updated the docs earlier today.

zvezdan

2022-05-04 18:05

updater   ~0067977

I don't understand how this issues could be marked as resolved. Almost nothing was changed regarding the better organization of the web site. And there is still a bunch of missing methods, properties and events.

Here is another example. I have spent several days to find out how to get OnSelect event for dropdown controls. My MM2-4 add-ons are using it for editable combo boxes when it is not enough just to have OnChange event. Where are all those events mentioned? Should I read several MB of your code just to find that out?

By the way, the old program was not much better with that control, it was wildly inconsistent. When the user clicks an item from the list: in the skinned version we had first OnChange then OnSelect (instead to have them opposite), and in the non-skinned version we had only OnSelect event without OnChange. It was always funny (i.e. frustrating) for scripters with your program.

drakinite

2022-05-04 20:43

developer   ~0067983

I closed the issue because I asked you to list methods whose documentation is inaccurate and you refused. There are genuinely hundreds of thousands of lines of code to go through, so it's easy to miss some.

Dropdown events are "change", "dropdownclosed", "keydown", and "popupclosed". They'll be up next time Jiri updates the docs on the site.

You don't have to be so aggressive, Zvezdan. If you can't find something on the API docs, just message me on the forum or send me an email. It's my job to answer questions from addon developers. It might be a surprise to hear this, but we're not your enemy. I want our developer documentation to be clear and useful just as much as you do. Have a bit of humility, and I'm sure we can work together effectively.

zvezdan

2022-05-04 23:16

updater   ~0067990

It seems that you missed my answer. So, here it is again.

"There is not only thing with "inaccurate" methods. There is a bunch of methods, properties and events that are not mentioned in API at all...

And how could I know as a user what your "app" object contains of these methods/events internally that is not mentioned in API? And many other objects that are part of your binary files, like "player" and similar. "

Here is one more example. Your Filesystem class is defined inside your binary files, not in JavaScripts. How could I know which methods are missing from it? Maybe to disassemble your .exe files? What about e.g. oFileObj.GetDrive(sDrvLetter).IsReady, do you have it available? Also, I don't see that getFileInfoAsync supports the read-only file attribute. In fact, one of my add-ons requires not only to read that attribute, but also to write it, i.e. I need setFileInfoAsync. Maybe I don't need to set the DateLastModified to the file, but someone could need it as well.

I don't need these events that you mentioned (beside of "change"). I need the same or similar events that my add-ons already used for 16 years. One of them is the mentioned "OnSelect". I cannot port my add-ons to MM5 if I don't have the same basic things that we had before. If you really care about porting of old scripts to MM5 as you state here and in the Forum, you should provide the safe and easy transition for that. The methods and events missing from API are not helping.

Someone of you started adding the "Supported in MM5?" column to the MM4 API about which methods have the correspondence in MM5 and stopped half a way just for the App object. And even that info was unpractical and not too much useful. If you wanted to do it right way, you should have provided names of the corresponding methods in MM5 with links to them, not just to say "Yes". Or, even worse, "No".

You are paid to go through hundreds of thousand of lines of code to do better web API, not me. However, you don't need to go through the code to see what is missing, you should go through the MM4 API to see that. For seven years you didn't do too much regarding that. And when I say "you" I don't mean on you personally, draknite, but on all you in Ventis Media.

petr

2022-05-05 06:53

developer   ~0067991

tip: open devtools and start typing in console like 'app.' and it will show you list of all methods and properties of the object

zvezdan

2022-05-05 06:54

updater   ~0067992

I finally found the equivalent to the OnSelect event: dropdown.controlClass.valuelist, 'focuschange'. Not thanks to you.

jiri

2022-05-05 15:55

administrator   ~0068001

Zvezdan, yes, the documentation is far from perfect, but we continuously work on its improvements. Feedback from addons developers definitely helps here, so that we know what's unclear and needs to be added/improved.

I understand that it isn't effective to spend time on searching something that possibly isn't in the docs yet. Feel free to ask anytime, I'd say that the forum is a good place, so that the answers can also help others in the future.

jiri

2022-05-05 16:07

administrator   ~0068002

The latest docs was uploaded. (To be continuously updated, together with more sample code)

Ludek

2022-05-06 20:29

developer   ~0068032

Last edited: 2022-05-06 20:40

View 4 revisions

FYI: Jordan just added further docs re https://www.mediamonkey.com/wiki/Controlling_MM5_from_External_Applications

As for the lack of documentation: Assigned to me as currently:
e.g. asJSON property isn't documented at all although majority of objects support it
Seeing that classes like track, artist, genre extends pinableObject that has documented some methods, but not the class itself. And pinnable object extends sharedObservable (where we could put the asJSON etc.)

So re-opened to document + traverse the code to see what should be documented further....

zvezdan

2022-05-06 22:18

updater   ~0068038

Maybe DevTools could be used to see which methods and properties are supported by some object, but it cannot tell which arguments are available to these methods and, even more importantly, it cannot tell which events are available to these objects.

Your API has some missing methods and properties, but events are almost non-existent. You have provided only events for App and player objects and you just recently added events for playlist and dropdown objects after my reports. Almost none other object has events covered. Here are the most important object for any GUI: Button (none event mentioned), Checkbox (it says "This class doesn't provide any methods, properties, attributes, or events." What the hell? How that object doesn't provide anything of that?), Edit (none), GridView (none), ListView (none), MediaTree (none), Scroller (none), Slider (none), Splitter (none), and so on. How do you expect that anyone create dialog boxes without events for these elements?

You didn't answer to me if your filesystem class has IsDriveReady method or something like that. You didn't answer if there is a way to get/set the read-only attribute of file.

And you are all avoiding to reply to my comment about poor organization of that API. Your list of objects on the left side is just a huge mess that is hard to navigate. Many of these objects are not really needed by scripters at all, but their including in it just make it hard to find something that is important. That list shouldn't have only one level, it should have the main objects on the base level and their sub-objects on the second and deeper levels. Or something like that.

You should also provide links to the related objects as much as it is possible. For example, when you choose root property of the playlists object, the description of that property should provide a link to the playlist object with its methods/properties/events, without forcing users to scroll that huge list of objects to find that object.

Ludek

2022-05-06 22:34

developer   ~0068040

Re events: almost every object has 'change' event. This will be documented by correcting the 'extends' to sharedObservable, to be fixed...

zvezdan

2022-05-06 23:06

updater   ~0068047

Re: traverse the code, as I said, you should traverse the MM4 API first. You have listed bunch of unimportant classes, but you missed some that are important to any GUI like Label. I didn't come to that part, but it seems that you didn't covered SpinEdit control or whatever you are calling it now. Here it the list that should be checked first:
SDBUIActiveX (yeah, that is not possible)
SDBUIButton
SDBUICheckBox
SDBUICommon
SDBUIDockablePanel
SDBUIDropDown
SDBUIEdit
SDBUIForm
SDBUIGroupBox
SDBUILabel
SDBUIListBox
SDBUIMaskEdit
SDBUIMultiLineEdit
SDBUIPanel
SDBUIRadioButton
SDBUISpinEdit
SDBUITrackBar
SDBUITranspPanel
SDBUITreeList
SDBUITreeListItem

drakinite

2022-05-07 00:58

developer   ~0068053

Last edited: 2022-05-08 00:07

View 4 revisions

The reason we don't respond to some of your comments is because you've been both gish galloping and deliberately baiting us into argument. I already said you don't need to be so aggressive, but as you've chosen to continue that path, so be it.

> "And you are all avoiding to reply to my comment about poor organization of that API"
I told you in 0019002:0067697 that we're using yuidoc to generate the page. Sorry but if you don't like how it's organized, that's not my problem.

> "You should also provide links to the related objects as much as it is possible. For example, when you choose root property of the playlists object, the description of that property should provide a link to the playlist object with its methods/properties/events, without forcing users to scroll that huge list of objects to find that object."
You can search for "Playlist". It's not hard.

> "You didn't answer to me if your filesystem class has IsDriveReady method or something like that"
It does not. Use app.filesystem.getDriveList(), which returns Promise<SharedList>.

> "You didn't answer if there is a way to get/set the read-only attribute of file"
There is not. If you would like there to be, create a new issue and we will triage it.

> "you missed some that are important to any GUI like Label."
"Label" control/objects are not needed in HTML/JS as you can create a label/div and set its innerHTML or innerText. For that reason, we don't have an equivalent.
SDBUIButton -> Button
SDBUICheckBox -> Checkbox
SDBUICommon -> Haven't worked with SDBUI, but from the documentation on the wiki, it seems like the analog is the superclass Control.
SDBUIDockablePanel -> Docking isn't fully documented now, but for the time being, check the comments in helpers/docking.js and for an example, check maincontent.html.
SDBUIDropDown -> Dropdown
SDBUIEdit -> Edit
SDBUIForm -> No equivalent. Use uitools.openDialog: https://www.mediamonkey.com/wiki/Important_Methods_and_Utilities_(Addons)#uitools.openDialog
SDBUIGroupBox No equivalent.
SDBUIListBox -> ListView and all its subclasses.
SDBUIMaskEdit -> Dunno what that is, sorry.
SDBUIMultiLineEdit -> Edit, but add multiline: true to its init params.
SDBUIPanel -> No equivalent.
SDBUIRadioButton -> Checkbox with type: 'radio'
SDBUISpinEdit -> Edit with type: 'number'
SDBUITrackBar -> Dunno what that is.
SDBUITranspPanel -> No equivalent. Use CSS.
SDBUITreeList -> TreeView
SDBUITreeListItem -> No equivalent. Use the TreeView's dataSource to change its items.

I'm still more than happy to having friendly discussions instead of sassy arguments if you decide to change your approach. It's much easier to message someone with a question than burying that question in a five paragraph essay. Saves time and energy.

zvezdan

2022-05-07 06:47

updater   ~0068054

> that's not my problem.

"Me, myself and I". I didn't know that you are the sole author of the program and its API. You are full of yourself glorifying your role with the program as if it is only you who spent years in its development.

Ludek

2022-05-08 18:46

developer   ~0068059

Last edited: 2022-05-08 18:52

View 3 revisions

Re the UI components, you can right-click the UI element in the debug build and select "Inspect Element" to see this:
https://www.dropbox.com/s/jjfs56eb5odg0vs/Screenshot%202022-05-08%2020.43.16.png?dl=0

This way you can see that what used to be SDBUIMaskEdit is now MaskEdit (data-control-class="MaskEdit") thus full source code for this component available in /controls/maskEdit.js

And as the whole UI is open-sourced in MM5 then there is no longer a need to document every UI component and method (as it's source code is mostly self-explanatory).

zvezdan

2022-05-08 19:16

updater   ~0068060

Thanks for the tip, although I already knew for that. Just some related notes:
- there are some controls that doesn't have the right-click context menu, e.g. the mentioned SpinEdit (which is now just Edit with data-init-params="{type: 'number', min:xx, max:yy}");
- you should include such tips in web API, not here;
- I didn't open this issue because of me, I don't need your web API.

However, there are some scripters who have the same frustration with your new API as I had, and who encouraged me in e-mail to "push you hard" (to quote some of them), in hope that we could see a real progress.

I told you several years ago in the Forum that the main problem with the new program and the scripts is your API. I explained that fact to some of you in e-mail as well. And you haven't done too much in meantime to resolve that. Too bad I didn't save the web pages of that initial API that you published seven years ago, just as a proof of my claims.

You are terribly wrong if you expect that all potential scripters will enjoy reading several MB of your code to find out things that should be better presented on the web API. Because of such attitude your own program is having poor acceptance by scripters, not mine.

If you like your API as it is right now and if you don't want to make it more approachable for new scripters, so let it be.

jiri

2022-05-09 20:19

administrator   ~0068069

Uploaded