Gnome extension development: how to get the basic documentation?

Platform
1

I am trying to start Gnome extension development. I created a new project using the default template which has a PanelMenu.Button, but where can I get the documentation for its methods and properties?

I opened https://gjs-docs.gnome.org/ , but it seems there are numerous categories and they are all disabled by default. So, I don’t what to enable to look up PanelMenu.Button. Shouldn’t all categories be all enabled by default for search?

Also, is there any way to get auto-completion and method descriptions for Gnome extension development in VS Code or in any other IDE/code editor? I thought that auto-completion might work out-of-the-box in Gnome Builder, but it did not. Is there currently no way, and all Gnome extension developers are developing without auto-completion or IDE’s help?

2

gjs-docs contains documentation for public library APIs, but PanelMenu is an internal implementation detail of GNOME Shell. There is not going to be any documentation. When you’re writing shell extensions, you are going to be working both with public documented APIs (which are stable), and with undocumented shell internals (which will change regularly and break your extension when they do). The way to figure out how those work is to read the code. That’s the deal with extensions: you can change anything you want because you have access to everything, at the cost that it’s going to be fragile.

I don’t know about autocompletion, sorry.

1 Like
3

I was about to add: “gnome-shell is not a library and you won’t find any docs for it on gjs-docs.gnome.org” but in fact it does provide some docs for a small public API here. I didn’t know about that. It’s not a lot, though, and doesn’t contain PanelMenu.

I don’t have a strong opinion on this, but normally you know what library you are using when searching for documentation so it usually won’t be a problem.

1 Like
4

Right, that’s for a small introspected C-library, so gjs-docs.gnome.org can handle it.

Extensions | GNOME JavaScript has some extension-specific documentation, including topics like popup menus or quick settings. Nothing for PanelMenu.Button specifically though.

2 Likes
5

Panel.Button was next on my list (I promise!), but at the moment the “API” docs for GNOME Shell’s JavaScript are being written by hand. Once GNOME Shell is ported to ESM, I’m hoping that will make auto-generating documentation for it possible.

Some other encouraging thoughts:

…is there any way to get auto-completion and method descriptions for Gnome extension development in VS Code or in any other IDE/code editor?

GNOME Builder will soon support plugins written in GJS, which should allow us to improve the JavaScript experience by exposing some of the existing tooling from the JS world.

I think this is not currently supported, though. VSCode probably have better built-in support for JavaScript in general.

Shouldn’t all categories be all enabled by default for search?

Changing the default docs have been a bit of a problem, but that’s a bug we want to fix. Enabling all of them would probably download them though, so we’ll probably pick a few.

1 Like
6

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.