JSDoc for Illustrator / VSCode

[Silly-V]

UPDATE: it turns out while whole thing was not necessary, we can use the existing Types for Adobe .d.ts files to auto-complete our regular .js files as long as VSCode is open as a folder and the d.ts file is also present in the workspace, opened up.

Hello all,

I am a slow-learner compared to some of you guys, but the story is, when I began to do Illustrator scripting, I was using the old ESTK. At the time I did not do any C# or use any other code editor, but automating some basic tasks was already a great payoff. Then, I began using Sublime Text and due to its features speeding my workflow, I switched to writing in Sublime and running from ESTK.

And sometime years later I went to VSCode driven in part by the fact that Adobe's new ESTK is a plugin in VSCode and not anywhere else that I know of.

Well, soon after I learned about JSDoc and how it can improve the development workflow even better by providing some auto-completion within VSCode. I'd be switching previously between files to see what properties I need to be writing here. Now, it seems like a convenient helper for all sorts of coding works where things get complex and auto-completion allows one to manage writing a huge number of programming constructs as is needed.

Unfortunately, VSCode JSDoc support is really lacking, although certain commands are listed in the official JSDoc site, VSCode does not recognize them or render their results properly - it's a work in progress and many have made the jump to TypeScript. However, even when doing TypeScript, JSDoc annotations still help, but as TS is used, JSDoc's shortcomings in VSCode are fixed by its great features.

For example, please view what I had to do in order to simulate the 'inheritance' of sub classes of art objects to the PageItem super-class to get it to do what I wished in VSCode:

/**
 * @typedef {Object} AiPageItem - Illustrator super-class of all art object kinds.
 *  {string} name - name of the item in Layers panel.
 *  {number[]} visibleBounds - Illustrator `visibleBounds` array: [left, top, right, bottom].
 *  {number} width - Width in pt.
 *  {number} height - Height in pt.
 */

/**
 * @typedef {Object} AiPathItemType
 *  {boolean} filled - True if this path has a fill color applied.
 *  {boolean} stroked - True if this path has a stroke width of more than 0 applied.

 * @typedef {AiPageItem & AiPathItemType} AiPathItem - Illustrator path, a single shape made from one bezier curve (which can have many segments). * 
 */

/**
 * @typedef {Object} AiCompoundPathItemType
 *  {AiPathItem[]} pathItems - The paths in this compound path.

 * @typedef {AiPageItem & AiCompoundPathItemType} AiCompoundPathItem - Illustrator Compound path, an object that contains one or multiple paths.
 * It can contain groups, which is an erroneous behavior and can lead to negative results.
 */

/**
 * @typedef {Object} AiLayer - Illustrator layer. Can be inside other layers as a sub-layer.
 *  {string} name - name of the layer in Layers panel.
 */

Anyways, I am posting this because I am curious if anyone else uses JSDoc for Illustrator/Adobe scripting and if there's already some resource where all the items are listed, such as Types for Adobe.

If not, I think the community could benefit from JSDoc due to these reasons:

1. Users who choose not to use TS can still get an autocompletion feature.
2. All you need is the document with all the types open in a workspace and you get the autocompletion!
3. If there's a standard JSDoc, forum visitors can open this file and if we annotate our snippets with @ type annotations, then every script code on here could be understood more in-depth quite quickly. In fact, they could build that into the forum if they wanted to - but seeing as there's not even an in-line code highlight button, I'm not sure that'll ever come to pass.

I welcome your feedback. Maybe hopefully I am missing something that there are ways to get VSCode JSDoc @ link and @ see and @ extends commands to work.

To add, come to think of it, they could build the typescript stuff into the forums too and provide instant expandable lists. However, JSX is an ES3 version of JS and simple JSDoc can work with everything! But unfortunately not fully developed inside of Microsoft's VSCode at least.

[CarlosCanto]

Hi Vasily, great topic, I would chime in but I don't know much about it. I'm adding it to my to-do list, sounds very interesting.

thanks!

[Silly-V]

Okay, I have at last created a 'port' of the Types for Adobe TypeScript type definitions into JSDoc. Now you can simply have this .js file open in your VSCode workspace and voila - you get auto-completion that helps you not be looking up rarely-needed obscure enumeration spellings in the Javascript Tools Guide PDF!

But check this out, if we go ahead and annotate the snippets in answers and have an instruction for users to have this file open, they will have such an easier time learning on why their script isn't working because a wrong property or spelling is being used.

Anyways, that's the hope, and from first tests this porting appears to work. However, I am going to be testing it out in my own real-life work to see how much it helps and where it may fall short, maybe there are some non-solved issues that are hard to find. The ts definition file is 11000+ lines long, so it's possible to make mistakes.

https://github.com/Silly-V/Adobe-Illustrator/tree/master/Types

Check it out and see if there's any problems and if it helps your workflow!

Also as a final note, while my conversion right now works on Types for Adobe .d.ts files, knowing with my new experience on JSDoc annotations, I think it's very doable to straight-up convert OMV XML files into JSDoc too. I have not looked at OMV in years now, but they may possibly have even more stuff in there.

[m1b]

Wow! This is awesome. I'll download and give it a go. Thank you! 🙂

[Silly-V]

Thanks, also watch out as I updated it some already and may make new changes later.

[m1b]

Ok, excellent! I had a quick try and noticed that there was no entry for ElementPlacement.

Also the entry for page item move method worked, but wasn't quite right:

It should show insertionLocation: ElementPlacement I think.

This is going to be *really* helpful for all of us struggling to remember!

- Mark

P.S. let me know if you'd prefer for me to open issues on the repo if I find anything in the future.

[Silly-V]

Yes, I also noticed this and checked the source TS file to make sure it's really not there. But it's not!

It totally is one of the most useful enums to have at-hand though, and I wonder how @Inventsable got that to work in the ovid editor: https://ovid-editor.web.app/ILST

Also the Illustrator d.ts file depends on the shared global.d.ts file, which isn't included here (yet).

The global file in turn depends on the javascript.d.ts file which contains even more of our basics.

However unlike the Illustrator types file, those files contain items that I wouldn't know how to necessarily parse out. For example, it's easy to take a statement of:

/**
 * The screen mode.
 */
declare enum ScreenMode {
  /**
   * Full screen with menu bar.
   */
  DESKTOP = 2,

  /**
   * Full screen without menu bar.
   */
  FULLSCREEN = 3,

  /**
   * Display multiple windows.
   */
  MULTIWINDOW = 1,
}

And turn it into:

/**
 * @typedef {Object} ScreenMode - The screen mode.
 * @property {2} DESKTOP - Full screen with menu bar.
 * @property {3} FULLSCREEN - Full screen without menu bar.
 * @property {1} MULTIWINDOW - Display multiple windows.
*/
/** @type {ScreenMode} */
const ScreenMode = {
	DESKTOP : 2,
	FULLSCREEN : 3,
	MULTIWINDOW : 1,
};

(This could be done differently, with the @ property items turned into @ type items inside the 'const', but I originally had made the typedefs without the 'const' at the bottom and afterwards I only realized that wasn't really doing the auto-completion I was hoping for)

But then the global and shared files have stuff like this:

/**
 * An XML list object.
 * In this implementation, an XMLList object is synonymous to the XML object. The constructor accepts an XML list, but everything else works like theXML object.
 */
interface XMLList {}
declare const XMLList: XMLList

interface UnitValueConstructor {
  readonly prototype: UnitValue

  /**
   * Creates a new UnitValue object.
   */
  new (value: string | UnitValue): UnitValue
  (value: string | UnitValue): UnitValue

  /**
   * The base unit for all conversions.
   */
  baseUnit: UnitValue
}
declare const UnitValue: UnitValueConstructor

And for those, I'm not even sure how to approach them. Most of those are very basic things that are in javascript anyway like the Error object, but others like the Socket object are not.

I actually hunted down the omv xml file (C:\Program Files (x86)\Common Files\Adobe\Scripting Dictionaries CC\illustrator 2021\omv.xml) and while there's ElementPlacement listed there as a linked item of sorts, I could not find its definition anywhere, so I wonder where it is linking from inside the omv?

[Silly-V]

Yes, everyone is welcome to open every issue that can be thought of!

[Silly-V]

Update: it turns out this whole thing is not necessary and we can just use the d.ts types for adobe files!

Here is what the behavior appears to be: VSCode helps with intellisense when either a JSDoc JS or d.TS files are opened and the VSCode workspace is open in a folder.

So all we have to do is open VSCode and open any folder. Then, open the types for Adobe .d.ts file and have it sitting in the same workspace. You still get all the benefits of intellisense from the .d.ts file with no JSDoc js file required!

So indeed, this whole exercise was a learning experience and a moot point!

[m1b]

So it doesn't matter if it's been marked up for JSDoc?

I just opened Type for Adobe/Illustrator/2015.3/index.d.ts and it works as you say. (However, as we knew, it doesn't have the .move() method or ElementPlacement.)

I know it was a reoundabout journey for you, but it was a clever idea, and it was good for my learning. TBH, I'm thinking that a file that simply enumerated all the constants would go a long way! I can never remember them. 🙂

- Mark

P.S. you've introduced me to JSDocs, too, which I'm glad to know about for future.

[Silly-V]

The JSDoc annotations are actually powered by the open d.ts file, they are for labelling your variables and function parameters for easy intellisense help, so it does the same thing as my JSDoc file and now that I've learned it works just the same in VSCode, it's case-closed. But yes the JSDoc markups still same and needed for auto-completion whether its the jsdoc file or ts file - both produce the same result which is to actually enable your annotations to perform it.

[m1b]

Ah! Of course it needs the markup. To know param types of a method for one example.

- Mark