Confusing API Documentation for PProPanel

[ericdrobinson]

There are several APIs listed in the PProPanel sample project's api_doc.html documentation that have misleading explanations. Specifically, the return value explanation is frequently at odds with the actual value returned. An example is Project.ImportFiles:

Returns 0 if Premiere Pro successfully imports the array of file paths. If suppressUI is true, no UI will be presented. if importAsNumberedStills is true, Premiere Pro will attempt to import the array as a still image sequence.

The documentation suggests that the function should return a falsey 0 in the case that the import was successful. Currently, and this is another bug, the example above always returns a boolean value of true, both on success and failure (testing was conducted with audio files).

This is the case for Premiere Pro 2017.1.

[bbb999]

Confusing documentation removed.

[ericdrobinson]

Well, two things about this:

1. Why simply remove all documentation about the return value instead of provide information about what the return value actually represents?
2. While I only referenced a single example in my initial ticket writeup, several other APIs suffer from the same issue. Another example would be the adjacent ProjectItem.importSequences: "Returns 0 if Premiere Pro successfully imports the sequences with IDs specified, from that project." As I pointed out at the end of the explanation, the writeup here suggests that the return value is a number whereas the Object Model Viewer claims that it is a boolean. I would also guess that the returned value is more nuanced than the explanation makes it seem, much as was the case with importFiles.

Perhaps a quick pass on the docs for this kind of issue would make sense?

[bbb999]

1. Because the return value didn't provide any useful information.

2. I can confirm that the Object Model Viewer is wrong about app.project.importSequences(). The return value will be non-zero only if an error is encountered within the function, and it takes two parameters; the path to a .prproj, and an array of Sequence GUIDs. I'll check with the helpful engineer who got the Object Model Viewer working, for PPro.

As previously mentioned, the documentation is being augmented and re-written.

[ericdrobinson]

1. Hmm... It sounds like documentation is getting overhauled so I understand hesitance in investing much time into this. In the meantime, for sleuths like myself, the "what does the boolean return value suggested by the OMV mean?" will continue to be a thing. If the chance arises, perhaps something like "The return value does not provide any useful information [and should be ignored]"? (Something like this obviously isn't necessary for void functions.) Much of the documentation effort could be thought of as pre-empting questions. ;)
2. Cool. It's interesting to hear that the OMV has some of the documentation wrong. It's a bit of a bummer as I used it to help generate a Premiere Pro Type Declarations file (as you're aware). Will have to proceed with caution where Premiere Pro ExtendScript API usage is concerned, I guess.

I wish you and the team luck on the documentation work!

[bbb999]

Much of the documentation effort could be thought of as pre-empting questions. ;)

VERY true—and it's a worthwhile pursuit.