v3.0.0

[znorman-harris]

Official release of the extension! See CHANGELOG and main README for more information.

---

This discussion was created from the release v3.0.0.

[cpiker]

Hi

Do you know how I can provide documentation for DLM functions in such a way that show up in vscode? Most of the software I create for IDL takes the form of binary DLMs bundling existing C code.

Thanks,

[znorman-harris]

That's a great question, and one that we have thought about, but we don't have anything implemented yet.

We actually have a couple of use cases for this: SAVE files and anything that comes from external sources like DLLs and DLMs.

Would you be up for a workflow like this?

• We will create a new file type for the extension that indicates a "type" file for IDL
• Write normal IDL syntax for routine definitions within this file (with arguments, keywords, and types for inputs/outputs). There would be no logic within the routines themselves, just the type signature and you would be able to use the automated documentation tools to create the starting point for you
• Include with your DLLs and DLMs and anyone else who uses the extension (or your code) would have access to the types

[cpiker]

That would be quite okay with me. Currently I include IDL style comments in the glue code. Maybe these could be copied out by a build script. Right now I put to docs on a wiki which is okay I guess, but they're not integrated into dev tools where they're needed.

Thanks for thinking about this. It would be gratifying see help for DLM functions (and maybe structures?) within VSCode.

[znorman-harris]

Thanks for the link to your code! The docs that we support in the extension follow the IDLDoc RST format (we have some backwards compatibility with the original IDLDoc format).

That means there would need to be some changes to your docs style.

For reference, here's some links showing how we documented the IDL code that is included as a part of the extension:

Procedure:

vscode-idl/idl/vscode/notebooks/idlnotebook/idlnotebook__define.pro

Lines 103 to 113 in 0fa8b8c

	;+
	; :Description:
	; This static method registers an item as needed to be embedded
	; within a notebook cell
	;
	; :Arguments:
	; item: in, required, !magic | IDLNotebookImage_Png | IDLNotebookImage_FromUri | IDLNotebookImage_AnimationFromUris | IDLNotebookMap | IDLNotebookPlot2D
	; The item we are adding to a notebook
	;
	;-
	pro IDLNotebook::AddToNotebook, item

Functions:

vscode-idl/idl/vscode/notebooks/idlnotebook/idlnotebook__define.pro

Lines 204 to 214 in 0fa8b8c

	;+
	; :Private:
	;
	; :Returns: OrderedHash<any>
	;
	; :Arguments:
	; item: in, required, Structure
	; The structure we are creating a notebook magic item from
	;
	;-
	function IDLNotebook::_CreateNotebookItemProps, item

Structure definitions in the "__define" routine:

vscode-idl/idl/vscode/notebooks/idlnotebook/idlnotebook__define.pro

Lines 444 to 507 in 0fa8b8c

	;+
	; :Description:
	; Class definition procedure
	;
	; :IDLNotebook:
	; enviListener: VSCodeENVIMessageInterceptor
	; If we have created an ENVI listener or not
	; graphics: OrderedHash<!magic>
	; By window ID, track graphics that we need to embed
	; items: List<any>
	; The items that we are adding to our notebook
	; mapItems: List<any>
	; The items that we are adding to a map for our given notebook
	; cell
	;
	; :IDLNotebook_LegacyMagic:
	; magic: OrderedHash<any>
	; An ordered-hash version of our !magic system variable
	; at the time of it being added
	;
	; :IDLNotebookItem:
	; item: OrderedHash<any>
	; The paired structure for the type of notebook magic
	; type: String
	; The type of notebook magic
	;
	;-
	pro IDLNotebook__define
	compile_opt idl2, hidden
	on_error, 2
	;+
	; Data structure for this class
	;-
	!null = {IDLNotebook, $
	enviListener: obj_new(), $
	items: list(), $
	mapItems: list(), $
	graphics: orderedhash()}
	;+
	; Legacy magic definition for all of our graphics
	;-
	!null = {IDLNotebook_LegacyMagic, $
	magic: orderedhash()}
	;+
	; Messages stored in `!IDLNotebookMagic`
	;-
	!null = {IDLNotebookItem, $
	type: 'string', $
	item: orderedhash()}
	; make sure super magic exists
	defsysv, '!IDLNotebookMagic', exists = _exists
	if ~_exists then defsysv, '!IDLNotebookMagic', $
	{IDLNotebook, enviListener: !false, items: list(), mapItems: list(), graphics: orderedhash(/fold_case)}
	; load all other structures
	IDLNotebookImage__define
	IDLNotebookMap__define
	IDLNotebookPlot__define
	ENVINotebook__define
	end

[cpiker]

Appreciate the pointers! I don't mind switching over the comment style at all, just happy to have a supported standard to follow. Will refer back to this discussion before I release the next version.

Cheers,

[znorman-harris]

@cpiker I know it has been a while, but we finally got to add in what we call Routine Definition files which allow you to have auto-complete and hover-help in VSCode.

TLDR: Normal PRO code without any logic in routines. Docs format following IDL Doc. If you have format on save enabled, and auto-doc, then the hard work will be done for you.

You can take a look here at our first pass.