docs: browserView.webContents can be null

[Juice10]

Description of Change

null was introduced as a possibility for destroyed webContents by @mlaurencin in: #25411

This change updates the documentation (and hopefully the typescript types) to reflect that.

Fixes: #40567

Checklist

• PR description included and stakeholders cc'd
• relevant documentation, tutorials, templates and examples are changed or added
• PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: browserView.webContents types now correctly reflects that destroyed webContents can be set to null

[welcome]

💖 Thanks for opening this pull request! 💖

We use semantic commit messages to streamline the release process. Before your pull request can be merged, you should update your pull request title to start with a semantic prefix.

Examples of commit messages with semantic prefixes:

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient is now available on Linux

Things that will help get your PR across the finish line:

• Follow the JavaScript, C++, and Python coding style.
• Run npm run lint locally to catch formatting errors earlier.
• Document any user-facing changes you've made following the documentation styleguide.
• Include tests when adding/changing behavior.
• Include screenshots and animated GIFs whenever possible.

We get a lot of pull requests on this repo, so please be patient and we will get back to you as soon as we can.

[Juice10]

I need some help, tried to get and failed to get the project running & reproduce the CI issue locally.

I copied another part of the docs hoping this issue would disappear but it looks like it keeps happening regardless. If anyone can help out this would be great!

I'm getting the following issue:

$ npm run create-api-json && electron-typescript-definitions --api=electron-api.json && node spec/ts-smoke/runner.js

> electron@0.0.0-development create-api-json
> node script/create-api-json.js

An error occurred while processing: "/home/builduser/project/src/electron/docs/api/browser-view.md"
AssertionError: Property `view.webContents` _Experimental_ should have a declared type but it does not: expected null to not equal null
    at _headingToPropertyBlock (/home/builduser/project/src/electron/node_modules/@electron/docs-parser/dist/block-parsers.js:103:49)
    at Array.map (<anonymous>)
    at parsePropertyBlocks (/home/builduser/project/src/electron/node_modules/@electron/docs-parser/dist/block-parsers.js:142:63)
    at DocsParser.<anonymous> (/home/builduser/project/src/electron/node_modules/@electron/docs-parser/dist/DocsParser.js:174:85)
    at Generator.next (<anonymous>)
    at fulfilled (/home/builduser/project/src/electron/node_modules/@electron/docs-parser/dist/DocsParser.js:28:58)
error Command failed with exit code 1.

[codebytere]

@Juice10 bullet points in properties aren't stylistically valid in our parsing logic - this should be removed. Bullet pointed items are parsed to refer to parameters passed to a function, of which a property would have none. Simply adding what you already did below:

A WebContents | null property that returns the WebContents owned by this view
or null if the contents are destroyed.

Fixes the issue. You can verify this by looking at the Archaeologist check in CI.

[Juice10]

@codebytere, thanks for the suggestion, I really appreciate it! Unfortunately I'm still getting the same error. I've even tried a couple variations on what you suggested, but the error is still the same.
Any chance you could take another look? I'd be happy to tweak it again, but I'm a bit lost in what to do.

[codebytere]

Did you try:

A WebContents | null property that returns the WebContents owned by this view
or null if the contents are destroyed.

[Juice10]

Replacing Returns WebContents | null with A WebContents | null fixed the issue!

I'm getting another issue now but it's no longer a docs parsing issue, but a typing issue so this is progress! Thanks for the help @codebytere

[codebytere]

thank for the fix (and for being patient through some snags!)

[codebytere]

oh fun, one more issue - not with the docs though! Looks like your change surfaced an actual types issue in lib/browser/api/browser-window.ts - we need to add a check for browserView.webContents being null in BrowserWindow.fromBrowserView (and return null if it is).

[Juice10]

Thanks for catching that @codebytere! I've added a fix for the issue you mentioned 16e636d. Hopefully this fixes it.

[nornagon]

you'll need to update the docs for BrowserWindow.fromBrowserView to state that it can return null, too.

[nornagon]

Looks like there are a bunch of type issues now in electron/spec/api-browser-view-spec.ts, which makes sense.

[zcbenz]

Add wip label as the CI failures need to be solved.