Better documentation of the Cinnamon API

[s3lph]

A thing I hate about Cinnamon (as a fairly unexerienced developer in this area) is the lack of an API documentation.

Even the most simple applet becomes hard to create - The only thing I could find was the Force Quit/xkill applet tutorial.

I think this is quite a sad fact, because Cinnamon is continuosly gaining popularity. With such a growing community comes a greater amount of developers.

JavaScript itself is easy to learn, but where am I supposed to learn the Cinnamon-specific stuff? Of course I can try to understand the commands and classes from the given applets, but so I will never learn what every specific command exactly does and I will certainly never know what commands exist.

So I think a complete API documentation for Applets, Desklets and Extensions is crucial for Cinnamon.

---

I already filed this at community.linuxmint.com, and they asked me to write this here

[ghost]

https://github.com/linuxmint/Cinnamon/pull/1629 https://github.com/linuxmint/Cinnamon/issues/1828 https://github.com/linuxmint/Cinnamon/issues/2835

[pdcurtis]

@theSeppi I agree with a lot of the points you make. That said, there are some excellent examples including @mtwebster's on Segfault. Even so I find too much is by learning from, or by copying, others code which is slow as much of it is undocumented and lacking comments. I have tried to document my code and identify bits which can be re-used but that may just be misleading others!

I am also not sure that is the whole of the problem. What is also badly needed is a place where applet developers can post some of our tips, tricks, resources, frequent issues, etc. to share and, of course a place to ask questions. I see no point in reinventing wheels. Unfortunately the Mint forums seem to pass much of the cinnamon content back to here as too specific.

It is also very good we have an easy way to make applets available to others but I have also become aware of some of the shortcomings. Many of the applets are not being updated but still have high ratings whilst newer applets get few people rating them now they can be downloaded and updated without even accessing the the Cinnamon Spices page. It is also unclear which version of Cinnamon the applets have been written for and tested against. Currently users can only find out by trial and error what still works by installing them. That said there are some very good applets and one can usually get a reasonable impression if one is prepared to read every comment. Unfortunately many users probably just download from within Cinnamon and never seem to visit Cinnamon Spices or give any feedback.

I have a number of other thoughts on what could be termed 'best practice' but I am probably already too far off the very specific title of this request!

[ChurchX]

Improvement of documentation is definite must have. Many times regarding few functionality i've seen several feature requests opened once again and closed again with "this can be done as applet". So time goes, and it only repeats again and again. Nothing gets done in stock applets, 3rd party applets are not written to implement those features either. I don't get how possibility to implement should be reason to not do it, and as there is no mechanism to vote for features by users, at very least lacking documentation should be improved to ease hurdles of more coders joining or to ease learning for new ones, if stock applet devs don't want to do. In addition to documenting coding applets imho there is need to document something like how to port gnome shell extensions to cinnamon applets as well, to lessen reinventing wheel, after all, cinnamon roots stem from gnome-shell fork, so there might be lot of reusable code instead of writing something from zero. How to debug. How to implement settings. How to implement gconf/dconf schema usage. Main types of applet UI elements with their parameters in depth. Interaction with themes. Description of different modules seen in applets/extensions, when and which should be used for what functionality (eg. GLib,Gio,Gtk,Shell,MessageTray,PanelMenu,Clutter,Lang,St,Meta,Main,DND,ExtensionUtils,Gettext and others) Advanced coding in examples How to interact with other api-s/programs/UI elements Best practices (including documentation/commenting code/code formatting/which api parts/coding ways are preferable to lessen possible work on maintaining for new cinnamon versions due deprecation some stuff) What is Not implementable via applet and when it should be made as extension. Main differences between gnome shell extensions and cinnamon applets regarding porting. More verbose advices on how to put resulting applet/extension @spices, where/how host it's source tree and maintain it .. And whatever else i didn't think of :). Yes, 15% of this might be documented, 50% more can be found by spending few months on reading other applets or gnome shell extensions, some share of lore can be googled up in small bits on different sites, yet nowhere it can be found in single place and covering enough. So each and every potential dev needs to spend that time and effort on digging shattered nfo bits by himself. I guesstimate that making 2/3rds giving up before even starting.

[collinss]

I've been saying for a while that it would be nice for us applet developers to collaborate, and I'm willing to contribute what I have learned (as are several others I've heard from), but there really isn't a good place for it that I have found. There's a wiki here on Github, and there is a little bit of documentation there, but the functionality is rather limited, and I don't think most people would think to look there anyway. I'm not sure what the best answer is to this issue, but something to aid in collaboration would certainly give a boost to the available spices.

[ghost]

I think no one is willing to write the basic documentation. I'm not able to do that, and even if I were I can not ... My English is poor. On the other hand I think we're all willing to talk about the most complex things we achieve do. And I think we're all willing to help and let to some one help us, but unfortunately that is not enough, so that more people will join us you need to have a guide with the basics.

I for one say it's not a matter of where it is going to do, because to begin to do, you also can use the wikipedia(http://www.wikipedia.org) without any problem. If this works and is there any specific place of cinnamon to move the documentation, it's could moved later. The matter that I see, is just difficult to start because the simplest things are what give more paperwork...

[highwindmx]

How about here?: https://github.com/linuxmint/cinnamon-spices/wiki (and send an announcement to the forum) I am not a programmer, but learning about creating x-let will bring lots of fun to me.

[pdcurtis]

Of the options so far I tend towards https://github.com/linuxmint/cinnamon-spices/wiki. The matching cinnamon one has some very out of date material but starting an cinnamon-spices one does seem consistent with previous practice. I also believe that any applets which are going to have wide application need to offer some possibility of continuity and it would be sensible to encourage use of Git itself for those applets so a bias towards git would be good.

Another home for material is the Mint Tutorials http://community.linuxmint.com/tutorial/search but a quick search came up virtually nothing on applets there.

It would be nice to have some input from @clefebvre, @mtwebster and others to make sure what is set up is consistent with the 'master plan'.

Do any of the contributors so far have any experience of 'design' of wikis? It would be nice to at least get the initial format correct that we are building on to avoid it becoming too unstructured.

A while back I had a shot at extending some of the existing tutorials so I could remember what I had done! If anybody is interested or even thinks it is worth building on it is at http://www.pcurtis.com//spices.htm#applet_techniques_and_tools. After the experts have stopped laughing constructive comments are always welcome (or provision of better offerings) !

[eman1986]

I agree it'd be nice if we had an api refence to work off of. I know JavaScript well and I'm open to learn anything new in programming, I hope I can figure out how to make an applet for cinnamon. So far it has been a bit of a pain. The tutorial I found is a good start but only scatches the surface sadly. Having access to an api reference would greatly assist me.

[collinss]

https://github.com/linuxmint/Cinnamon/wiki/API-reference

Here's a start at least. I'll try to keep adding to this as I have time, but any help here would be appreciated.

[pixunil]

I think we could use some kind of automation, a python file, which reads all javascript files, looks for documentation comments, like the "class" definition for MenuItem in js/ui/applet.js:

/**
 * #MenuItem
 * @_text (string): Text to be displayed in the menu item
 * @_icon (string): Name of icon to be displayed in the menu item
 * @_callback (Function): Callback function when the menu item is clicked
 * @icon (St.Icon): Icon of the menu item
 * 
 * A menu item that contains an icon, a text and responds to clicks
 * 
 * Inherits: PopupMenu.PopupBaseMenuItem
 */

If we format this into (GH) markdown, we could dynamically build the documentation and we have no double work.

I started this at branch docbuilder of my fork. pixunil/Cinnamon:docbuilder

[mtwebster]

I'm pretty sure this already exists: https://github.com/linuxmint/Cinnamon/tree/master/doc

[ghost]

Yes @pixunil, please also read this: https://github.com/linuxmint/Cinnamon/pull/1629

[pixunil]

This is great work, I just wondered if we could also do this as Markdown output. (You know, for the wiki)

[dalcde]

This is an experimental attempt at code documentation: http://dec41.user.srcf.net/cinnadoc/ http://linuxmint.github.io/reference/

[dalcde]

For those interested in contributing to documentation and tutorials, here are the guidelines regarding how to document code and write tutorials under the current system:

http://linuxmint.github.io/reference/git/cinnamon-js/documenting-source.html http://linuxmint.github.io/reference/git/cinnamon-js/documenting-tutorial.html

Code documentation is written inside the code itself with comment blocks, while tutorials are separate .xml files. Currently, all tutorials have to be written in docbook format, which is a bit like html but the tag names are longer.

NOTE to self: write a docbook crash-course tutorial

If you don't wish to learn the devious docbook format, there are certain online converters from other languages to docbook, eg. https://foliovision.com/seo-tools/pandoc-online. However, conversion from Markdown is usually not very successful. I suppose more structured formats such as LaTeX will produce better output, but I haven't tried. Regardless, there will always be some need of fine-tuning the sectioning and layering to fit into the general structure.

If anyone writes some tutorial in non-docbook format, I wouldn't mind help converting them to docbook afterwards. After all, it is easier to do the conversion than write one myself :) However, if you plan to write a non-trivial amount of tutorials, it would be a good idea to learn the docbook format.

ETA: to clarify, all documentation and tutorials are in the codebase and additions should be submitted via pull requests since they are embedded inside the codebase. If the tutorial needs polishing, you can put it somewhere else (eg. pastebin/github wiki) and someone else can polish it for you and make a pr.

[plainas]

I am sorry I am commenting on this old issue. But I though I would share what I experienced when I tried to develop an extension for cinnamon.

Desktop management APIs have historically been poorly documented. I don't know if it is a tradition, but this can even be observed in projects like Xlib or ncurses. Sadly cinnamon suffers from that condition too.

I wanted to do simple things: grab a list of windows, fire up a notification or a popup from the tray, resize a window... the APIs to do this should be documeted and easily navigable and searchable. Why don't we have a list of method signatures for things like this?

At my first try, I gave up because there was no documentation and no mailing list nor any forum where I could ask simple things. When I tried again, I was a little bit more determined and eventually got quite a bit of stuff to work by looking at the source code of other extensions and learning from it. But that doesn't work all the time and it was too time consuming.I eventually got bored.

I hate to sound so negative as I appreciate the work of the good people that put cinnamon together. But it is a fact that lack of more and more accessible documentation and a discussion platform is resulting on cinnamon missing out on many potentially interesting contributions.

[mtwebster]

http://developer.linuxmint.com/index.html

Not sure how visible that link is publicly - but that's most of our API as well as a lot of tutorial info. It's not everything, however - you'll still want to look at other peoples' work for what's really possible, and libraries we don't control, but utilize (clutter, gio, glib, etc..) aren't included there.

There's no mailing list - your best bet is irc - see the Contributing page at that site.

[ghost]

@mtwebster Maybe a link to the documentation inside the cinnamon readme and also inside spices, will be helpful to find easy the documentation. Also a thread in segmentfault to speak about this and a permanent post in mint forums? Is a big work in my opinion and i think also user will want to know that cinnamon devs also provide help to others.

[JosephMcc]

As mtwebster pointed out there is now a website that is home to the cinnamon documentation. If you have cinnamon-doc installed it will also show up in the devhelp application.

[IzzySoft]

@JosephMcc While that is technically true, it's currently rather a "skeleton". Beginners will have issues following the short API reference, and the few examples/tutorials don't go very far. True, it gets you started with a simple applet (like that XKill example). But if I want to implement something beyond that (e.g. show some simple graphs), I'm already lost. So it would be nice to have at least a little list with additional links, which could be wiki-style for folks to add to, and should be linked to from the main reference.

[attila123]

I am a total beginner here, just wanted to modify an applet and had trouble with it. First of all, I needed to restart Cinnamon, otherwise the applet did not update even if I removed, added it. I found a "Restart Cinnamon" applet for that (can be downloaded e.g. in the Applets -> Download tab). What I found useful: the imports.ui. stuff seems to be installed at /usr/share/cinnamon/js/ui For e.g. 'imports.gi.St': global.log() may be your friend e.g. const St = imports.gi.St; global.log(St); The logs can be followed in the lg (Melange application) (Alt + F2, then type: lg), at the 'Log' tab, or in ~/.cinnamon/glass.log. Hope it helps someone...

[mscheper]

Five years have passed, this issue is closed, but I think it's still relevant. I've got a good 20 years of dev experience, including desktop apps and plenty of JavaScript/ECMAScript, but writing even a basic applet seems daunting and tedious to me at this stage.

From the comments above, it seems people have tried to solve this problem, but any effort has been scrubbed:

How about here?: https://github.com/linuxmint/cinnamon-spices/wiki – @highwindmx

404

http://linuxmint.github.io/reference/ – @dalcde

404

https://github.com/linuxmint/Cinnamon/wiki/API-reference – @collinss

Empty page.

http://developer.linuxmint.com/index.html – @JosephMcc

Yeah, but there really isn't much there. The only thing about applets there is the article about x-kill, which was mentioned in the OP. It's not useless, but I've had to do a lot of digging around StackOverflow and Google for what seems essential information, and I'm still feeling quite lost. That article seems to be written for novices, but I doubt any of them have lept into code up to their armpits.

If you have cinnamon-doc installed it will also show up in the devhelp application

True, but the tutorials it has are, again, the same problematic ones mentioned in the OP, and they don't seem to be up-to-date. For example, there's no mention of the PopupMenu.PopupSliderMenuItem that I've seen in some applet code. Then again, since a Google search for that came up blank, I don't think there are docs for that anywhere! 😮

I feel bad for just whinging, but since I don't have many answers, I don't feel qualified to write any docs myself. But I'll summarise a few things I have found, for anybody else who finds this page:

• cinnamon-looking-glass I a pretty essential debugging tool; just launch it from the command line. You can also log to it from your applets, like this: global.log('some string', someObject);—it works similarly to console.log in a browser
• To restart your applet, type dbus-send --session --dest=org.Cinnamon.LookingGlass --type=method_call /org/Cinnamon/LookingGlass org.Cinnamon.LookingGlass.ReloadExtension string:'your-applet-UUID' string:'APPLET', where your-applet-UUID is whatever you chose in your metadata.json file ← take note @attila123
• I've found some rather minimalistic API docs at http://lira.epac.to:8080/doc/cinnamon/cinnamon-js/ but I think it's the same out-of-date stuff as in devhelp/cinnamon-doc. Also, the promise that 'The latest version of this documentation can be found online at http://developer.linuxmint.com/reference/git/cinnamon-js/' is a lie

Despite all this, enough applets exist to suggest there's a trove of docs somewhere… either that, or they're all written by experienced Cinnamon devs, or people a lot more patient than I. 😉 Can anybody point to such a trove? I do love Cinnamon, and would love to contribute to it.

[IzzySoft]

@mscheper thanks for summing it up! That reflects exactly my experience. As I got no answer (my post above is more than 2 years old) and neither could find help elsewhere, I meanwhile gave up. I simply lack the time to "play around" for days to find out how to get a simple "hello world" line printed (figuratively spoken). Seeing that, 2 years later, the situation has not changed is not exactly encouraging.

[jaszhix]

This is your answer:

As mtwebster pointed out there is now a website that is home to the cinnamon documentation. If you have cinnamon-doc installed it will also show up in the devhelp application.

Install cinnamon-doc and devhelp packages. Run devhelp.

This is the same content that was on the previous developer website, but more complete.

Despite the word "extension", you really need to be familiar with cinnamon's source to be effective with extending it - you are after all, modifying its running state. There's no sandboxing here, it's just a way to make parts of cinnamon portable. I suggest taking the time to learn how the part of cinnamon you're affecting works. It changes often, and I know we do keep the jsdoc tags updated. The build system for the docs doesn't make them available online, though. Its trivial to get them in devhelp like mentioned above, and I think that is an adequate response.

I've tried to make the developer experience better, with a log function that behaves more like console.log, a commonjs-like module importer, for instance. I have definitely documented the latter. Efforts have been made, but they're incomplete, and it is now up to you to want to learn and experiment. To become a developer yourself and help complete the docs. Docs are only one part of a good developer experience, so I disagree with the general sentiment here - nobody is being ignored, and I personally care about cinnamon being easy to develop for. There's just few of us though.

If you're able to write code, please write code and don't poke a stick at a two year old zombie issue.

[pdcurtis]

This is an old problem which keeps coming up in some form or other. The documentation is much much better than it was and this issue was correctly closed a long while back. In addition there are a number of core team members who have given me considerable help when required, many have contributed to this thread.

The fact that people keep coming back however means that it may not be easy to find the documentation and I wonder if an obvious link/reference to devhelp is required in some of the git README.mds, in particular or the extensions

[collinss]

FYI, a developer guide has been on the roadmap for a while, and one of the things that would be there would be instructions on how to access the documentation. It's been pushed back a few times for lack of time to implement it, but it will happen eventually.

[mscheper]

This is your answer:

As mtwebster pointed out there is now a website that is home to the cinnamon documentation. If you have cinnamon-doc installed it will also show up in the devhelp application.

Thanks, @jaszhix, but did you read my post? I explained the problem I was having with that. I even quoted that exact paragraph.

I do appreciate the log feature you added, though—I mentioned that in my post, too.

[jaszhix]

I read your response, but to me it sounded like you were referencing the material intended for the developer site. If there's nothing in devhelp, that means it needs a doc tag.

True, but the tutorials it has are, again, the same problematic ones mentioned in the OP, and they don't seem to be up-to-date. For example, there's no mention of the PopupMenu.PopupSliderMenuItem that I've seen in some applet code. Then again, since a Google search for that came up blank, I don't think there are docs for that anywhere! open_mouth

Reopening because there's no other open issue for this, and it's clearly in need of improvement.

[mscheper]

Thanks, @jaszhix.

For the general 'getting started' issue, here's what I request, and can offer: If you can point me to a forum where it's appropriate for me to ask n00b questions, I'll try to write the applet I want, and write some general docs along the way. I have 20 years' of JavaScript experience, so hopefully, once I've received some tips for setting up an environment for testing and debugging Cinnamon apps, I'll be able to write something to help people get their feet wet. Or maybe I should start with a blog post, and give people a chance to comment.

Also let me know where to submit what I wrote, so it can be considered for cinnamon-doc.

Also, I think it would help tremendously if somebody at least mentioned the cinnamon-doc, and how to view it, at this site. Judging from the comments above, right or wrong, it's where most people first go to look for help on this topic.

[collinss]

@mscheper we (those of us on the Linux Mint/Cinnamon team) used to all hang out on irc where anyone could drop in and ask questions. I believe the channel is still there, but we switched to Slack a few years ago, so I don't think much happens there these days. Slack was a nice change for the team because it made it easier for us to communicate, but it also made it harder for anyone else to reach us. So more recently we created a second slack workspace so that people who were tangentially related to the project could still communicate (such as applet devs). It's a bit more quiet there than our main workspace, but most of the team is there (and several applet devs too), so if you ask a question, you'll usually get a response pretty quickly. If you want we can send you an invite. We'll just need an email address to get you on. If you don't want to post your email here (can't blame you for that), you can look up one of us and send it to our email.

[mscheper]

@collinss Thanks. I, too, eventually jumped on the Slack bandwagon, but it does create somewhat of a community barrier.

If you can create an account for me with the address cinnamon 0x40 michaelscheper 0x2E com then I'll receive the credentials, and it'll be easy to send email to /dev/null if it starts getting spammy. Thanks!

[collinss]

@mscheper Ok, invitation sent.

[ngaro]

2 more years have past, and it seems that this issue only contains dead links... When will some API docs be available ? If they are bad and incomplete, it would be a petty but i could survive. Just make sure they exit...

Either put them in this repo or place the location in the README.md

[JosephMcc]

There are API docs and have been for a long time. You need to install the cinnamon-doc package and devhelp. Then the docs will be there.