registerWalkthrough API comments

[roblourens]

This is a little confusing as a public API. Adding a step inside getingStartedContent was easy, but there is some preprocessing that the service does internally when registering a walkthrough.

• Seems like I have to pass the steps in twice, in the IGettingStartedWalkthroughDescriptor#content and the second argument
• 'when' should be optional on the step
• Could document how completionEvents works
• The description type is confusing when I want a normal string
• Setting up media is confusing, could use a helper or some guidance. I copy/pasted and it worked but it feels like I'm repeating myself

[roblourens]

I also get this when reloading the window gettingStarted.ts:775 Could not restore to category notebookProfileWalkthrough as it was not found (my contrib registers too slow?)

and this

Trying to add a disposable to a DisposableStore that has already been disposed of. The added object will be leaked!
    at DisposableStore.add (lifecycle.ts:177)
    at GettingStartedIndexList._register (lifecycle.ts:207)
    at GettingStartedIndexList.register (gettingStarted.ts:1322)
    at gettingStarted.ts:877

[JacksonKearl]

Now:

registerWalkthrough(descriptor: IWalkthrough): void;

export interface IWalkthrough {
	id: string
	title: string
	description: string
	order: number
	source: string
	isFeatured: boolean
	next?: string
	when: ContextKeyExpression
	steps: IWalkthroughStep[]
	icon:
	| { type: 'icon', icon: ThemeIcon }
	| { type: 'image', path: string }
}

export interface IWalkthroughStep {
	id: string
	title: string
	description: LinkedText[]
	category: string
	when: ContextKeyExpression
	order: number
	completionEvents: string[]
	media:
	| { type: 'image', path: { hc: URI, light: URI, dark: URI }, altText: string }
	| { type: 'svg', path: URI, altText: string }
	| { type: 'markdown', path: URI, base: URI, root: URI }
}

[JacksonKearl]

Oh just remembered LinkedText => string, will address.