View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0018999 | MMW 5 | Extensions framework | public | 2022-04-22 22:28 | 2024-10-22 04:22 |
| Reporter | zvezdan | Assigned To | |||
| Priority | urgent | Severity | minor | Reproducibility | N/A |
| Status | assigned | Resolution | reopened | ||
| Product Version | 5.0.3 | ||||
| Target Version | 5.0.4 | ||||
| Summary | 0018999: API is unorganized, poorly documented, with many things missing or wrong | ||||
| Description | Just 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. | ||||
| Tags | No tags attached. | ||||
| Fixed in build | |||||
|
|
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. |
|
|
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. |
|
|
Tagging as resolved since Jiri apparently updated the docs earlier today. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
tip: open devtools and start typing in console like 'app.' and it will show you list of all methods and properties of the object |
|
|
I finally found the equivalent to the OnSelect event: dropdown.controlClass.valuelist, 'focuschange'. Not thanks to you. |
|
|
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. |
|
|
The latest docs was uploaded. (To be continuously updated, together with more sample code) |
|
|
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.... |
|
|
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. |
|
|
Re events: almost every object has 'change' event. This will be documented by correcting the 'extends' to sharedObservable, to be fixed... |
|
|
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 |
|
|
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. |
|
|
> 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. |
|
|
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). |
|
|
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. |
|
|
Uploaded |
|
|
FYI: We are working on translating our source code to TypeScript, and we are using TypeDoc to generate documentation for those TS files. It's not complete, but the new API docs are located here: https://www.mediamonkey.com/docs/apinew/ |
|
|
Hi Zvezdan, the new docs (https://www.mediamonkey.com/docs/apinew/) are still not complete, but they are further along than when this issue was last updated. If you could give feedback on the new docs, that would be greatly appreciated, including improvements that should be kept and weaknesses that should be worked on. Classes in the Native module are generated automatically via a script that parses the Delphi source code, so there should no longer be any errors caused by typos. One issue we're already aware of (which will slowly be worked on) is that some functions' parameters are declared as "any[]" and return values are sometimes "any" or "Promise<any>", since those parameter/return types need to be manually entered. Everything else is fair game and I'd appreciate feedback/ideas on how to make the new API documentation more digestible. |
|
|
Thanks for working on this. It seems that the new docs have somewhat better organization than before. I didn't check if there are still any missing/incorrect descriptions, but if you are interested about my opinion on the structure of the web pages, here are my suggestions: - many pages have too many texts, including the main page (MediaMonkey API Docs), they are downloading/opening very slowly and they require too much scroll; - the tree on the left should have more levels, not just 2 (not counting the main MM API Docs level). For example, the Controls / ListView page requires 110 PageDowns to scroll to the bottom (yeah, I counted it, on 3000x2000 screen, 200% scaling, approx. 30 lines per page gives about 3000 lines for that page). The list of names of all properties/methods/events/... linked to their descriptions is displayed only on the top of the page, which requires too much scrolling to the top just to be able to access that list (e.g. when you choose one method, the page will be jumped to its description, and then if you want to see another method of the same object you need to scroll to the top to be able to choose and see that another method). I think it would be better if such linked list of properties/methods/... is presented as a sub-level of the tree for such object/item, e.g. Controls / ListView could have all its properties/methods/... on the third sub-level. And when you click on such item in the tree, only that method would be displayed. As you know, the shorter web pages with less text are faster to download and the navigation would be more smoothly. In my opinion, all pages should require as less scrolling as possible, which would be if they have about 30-40 lines and no more than maybe 100-150 lines. Also, I think the whole Settings frame on the right would be better to be included somehow as a sub-level of the main MediaMonkey API Docs tree item; it seems it is used only for that item/page and for other pages it is just consuming the horizontal space unnecessarily; By the way, I remember the days when full MM API was distributed with the program using CHM file. I still think it was wrong when you decided to ditch that. It was much faster than accessing Web and didn't require Internet connection. |
|
|
Thanks for the detailed feedback! Re pages loading slowly: I don't follow how the pages load slowly, unless your internet connection is very slow - The largest of the html pages are a few hundred kilobytes. But since you pointed out slow page times, I just noticed that the background loading of search.js can take a very long time, because it's an astounding 11 MB. Thankfully, the newest version of typedoc seems to be shaving both sizes down by reducing the number of items in the search index and not including ALL dropdown data in every html file. Is your slow page load time due to the loading of search.js, or is the initial page load always slow? I like your ideas and I'll see how many are feasible to do in our typedoc theme. I think instead of putting the settings on the left, maybe it could be made to be collapsible horizontally, i.e. click a ">" button to make it take up only a few dozen pixels on the right of the screen. I think there used to be more dropdown items on the right side of the screen but were later removed from typedoc. Re reducing page height: I can see there's a lot of wasted horizontal space on most entries due to each thing having its own line (each property has a separate line for its title, type, and every flag) - It may get complicated but it'd probably be worth trying to combine multiple lines into one. Re CHM files: I just did a quick look-up to see if it's possible to compile this Typedoc (which is really just a folder full of HTML files) into a CHM file, but the software for creating CHM files is ancient and I'm not sure if it's feasible. But since everyone has a web browser, and the Typedoc HTML files can be opened in a web browser with everything working as expected, maybe the documentation could be bundled into the installer and optionally extracted into the install folder. I wouldn't put it as a high priority, though, since people may miss out on documentation improvements (when we update the docs every few months or so) if they exclusively read the offline ones that came with a specific release of MM5. |
|
|
Yeah, the main page and many other pages are always loading slowly, even after going to another page and then back to the main page again. I have 15 Mbps Internet connection, but the laptop is accessing it through WiFi. It is especially problematic in my case when the laptop is working on battery, because I have maximum processor state custom set to 80% for longer work without being plugged-in. Anyway, when you are designing the web pages, you should always do it thinking on the worst scenario, because you don't know in advance in which conditions users would access these pages. I think you misunderstood me, I didn't suggested reducing page height. I had two related suggestions: 1. reduce the number of lines per page to eliminate too much vertical scroll, i.e. parse pages containing too much lines into more pages containing less lines (I explained how would you do that by putting each method of every object into separate page), 2. remove the right side Settings frame to eliminate horizontal empty space on the page. I think any way for having the offline API documentation is better than none. You don't need to distribute it along with the program, but you could put a link to it on the main API Web page allowing its download. And then you need to update that file every time when you modify some contained HTML page. Yes, that would be additional work for you, but I am sure that many scripters would appreciate it. If you don't have any useful CHM software, maybe you could create the EPUB file instead. There are many readers for such format, e.g. Calibre, and that format is nothing else that renamed ZIP file containing HTML files. Well, maybe it is not simple as that, but not too much. By the way, I don't recommend PDF format for such thing at all. |
|
|
I just noticed that the source code of program is now much better for navigation, e.g. using Go to Definition in VSCode, especially with TypeScript files. I just compared the same files in different versions, the things started to improve drastically with 5.1. There are still many red lines in the scrollbars of VSCode indicating that it "Cannot find name ...", but far less than before. Big thanks! |
|
|
I'm glad that the introduction of TS has been helpful! I'm personally a big fan of the way TS allows for much better in-IDE language features. |
