Returning None from a command's description method generates console errors

[OdatNurd]

Summary

The API documentation for TextCommand, WindowCommand and ApplicationCommand all mention that the description method can return None to get the default description. However, doing so (while having the intended behaviour) also causes Sublime to generate error messages to the console.

If the method returns an empty string, the behaviour is to use the default description without generating an error. As such I am unsure if this is a bug in the API documentation, the core itself, or both.

Expected behavior

As documented, returning None from the description method should cause the default description to be used in the menu without generating an error message to the console.

Actual behavior

For every call to the description method where the method returns None, the console displays the error message TypeError: String required, although the default description is indeed used in the menu caption.

Replacing the return value of None with an empty string causes the menu caption to be the default description without generating the above error message.

Steps to reproduce

As referenced in the images above, the contents of Packages\User\Context.sublime-menu is:

[
	{ "caption": "-" },
	{ "command": "sample_text" },
	{ "command": "sample_window" },
	{ "command": "sample_application" }
]

Additionally, the contents of Packages\User\sample.py for the failure case is:

import sublime
import sublime_plugin


class SampleTextCommand(sublime_plugin.TextCommand):
	def description(self):
		print("-> text: None")
		return None

class SampleWindowCommand(sublime_plugin.WindowCommand):
	def description(self):
		print("-> window: None")
		return None

class SampleApplicationCommand(sublime_plugin.ApplicationCommand):
	def description(self):
		print("-> application: None")
		return None

As shown in the images above, although the context menu does indeed use the proper default caption, the return value of None causes the core to generate an error message to the console as well.

Looking inside of sublime_plugin.py at the implementation of the Command class that is the base call for all other command classes, the default description method returns an empty string, and modifying the code above to do that suppresses the error message but still has the intended effect.

Based on this it seems like perhaps the intent of the API documentation is to state that you should return an empty description, but it's written as None, and that internally the core is interpreting that as an error, logging it and then treating it as an empty string anyway.

Environment

• Operating system and version:
  • Windows 7
  • Mac OS 10.10.5
  • Linux
• Sublime Text:
  • Build 3092 through 3142

[BenjaminSchaaf]

Fixed in Sublime Text 4.