API Documentation Bugs

[Thom1729]

I've gone through the API documentation and compared it to the sublime package source to come up a list of inconsistencies. Most of these fall neatly into one of two categories:

Undocumented functions or methods

A good many functions and methods are not documented. In some cases, this may be deliberate. In these cases, the function or method might benefit from a comment indicating that the feature is for internal use only. In other cases, the functionality might be very useful to package developers and ought to be documented. The following examples stand out:

• sublime.channel()
• Window.settings()
• View.is_valid()
• View.close()
• View.meta_info() (As observed in [API Documentation] missing view.meta_info method #1437.)
• View.indentation_level(pt)

Incorrect argument names

In many instances, the documented argument names do not match the names in the Python source. This matters when developers try to call API functions and methods using keyword arguents. Because some API methods have many optional arguments, this can be a real obstacle for developers. What inspired me to compile this list was the Window.show_quick_panel method. The signature described in the documentation is:

show_quick_panel(items, on_done, <flags>, <selected_index>, <on_highlighted>)

However, the actual signature is:

show_quick_panel(items, on_select, <flags>, <selected_index>, <on_highlight>)

There are two possible remedies to this: to change the documentation or to change the module. Changing the documentation is easier and does not run the risk of breaking code. In some cases, the argument names in the documentation may help to document the type of the argument; this information might instead be documented in the style of Python 3.5 type hints:

run_command(
    cmd: string,
    args: dict
)

It would be possible to alter the argument names without breaking compatibility by using a decorator mapping old argument names to the current documented names (and possibly emitting a deprecation warning). This might be a good way to preserve backward compatibility in a new version of sublime for a new Python runtime.

sublime

Undocumented functions

• channel()
• executable_path()
• executable_hash()
• status_message(msg)
• log_indexing(msg)
• log_build_systems(msg)

Incorrect argument names

Function	Actual Name	Documented Name	Notes
error_message	msg	string
ok_cancel_dialog	msg	string
ok_cancel_dialog	ok_title		An empty string will be ignored.
yes_no_cancel_dialog	msg	string
yes_no_cancel_dialog	yes_title		An empty string will be ignored.
yes_no_cancel_dialog	no_title		An empty string will be ignored.
run_command	cmd	string
set_clipboard_command	text	string
score_selector	scope_name	scope
encode_value	val	value
decode_value	data	string
expand_variables	val	value
set_timeout	f	callback
set_timeout	timeout_ms	delay	Optional, defaults to 0.
set_timeout_async	f	callback
set_timeout_async	timeout_ms	delay	Optional, defaults to 0.

Window

Undocumented methods

• Window(self, id) (probably private)
• hwnd(self) (probably private)
• transient_sheet_in_group(self, group)
• transient_view_in_group(self, group)
• layout(self)
• get_layout(self) (deprecated)
• set_layout(self, layout)
• get_output_panel(self, name) (deprecated)
• settings(self)
• template_settings(self)
• lookup_references_in_index(self, sym)
• lookup_references_in_open_files(self, sym)

Incorrect argument names

Method	Actual Name	Documented Name	Notes
run_command	cmd	string
open_file	fname	file_name
open_file	flag		The FORCE_GROUP flag is undocumented.
open_file	group	undocumented
find_open_file	fname	file_name
focus_group	idx	group
set_sheet_index	idx	index
set_view_index	idx	index
show_quick_panel	on_select	on_done
show_quick_panel	on_highlight	on_highlighted
set_project_data	v	data
lookup_symbol_in_index	sym	symbol
lookup_symbol_in_open_files	sym	symbol
status_message	msg	string
new_file	flags	undocumented
new_file	syntax	undocumented

Region

Undocumented methods

• __str__(self)
• __repr__(self)
• __len__(self)
• __eq__(self, rhs)
• __lt__(self, rhs)

Incorrect argument names

Method	Actual Name	Documented Name	Notes
Region	b		Optional, defaults to a.
Region	xpos	undocumented
contains	x	region and point
cover	rhs	region
intersection	rhs	region
intersects	rhs	region

Notes

The implementation of __lt__ is a bit idiosyncratic. Because the method is undocumented, it might be safe to redefine the operator in a new version of the API.

Selection

Undocumented methods

• Selection(self, id) (probably private)
• __len__(self)
• __getitem__(self, index)
• __delitem__(self, index)
• __eq__(self, rhs)
• __lt__(self, rhs)
• __bool__(self)
• is_valid(self)

Incorrect argument names

Method	Actual Name	Documented Name	Notes
add	x	region

Notes

The __iter__ method is not implemented. Iteration over a Selection will still work because Python will fall back to using __len__ and __getitem__, but some modern means of checking for iterability may fail on Selection instances.

View

Undocumented methods

• View(self, id) (probably private)
• __len__(self)
• __eq__(self, other)
• __bool__(self)
• is_valid(self)
• close(self)
• retarget(self, new_fname)
• begin_edit(self, edit_token, cmd, args) (probably private)
• end_edit(self, edit) (probably private)
• is_in_edit(self) (probably private)
• meta_info(self, key, pt)
• indented_region(self, pt)
• indentation_level(self, pt)
• has_non_empty_selection_region(self)
• is_folded(self, sr)
• folded_regions(self)
• add_phantom(self, key)
• erase_phantoms(self, key)
• erase_phantom_by_id(self, pid)
• query_phantom(self, pid)
• query_phantoms(self, pids)
• assign_syntax(self, syntax_file)
• indexed_symbols(self)
• indexed_references(self)
• extract_completions(self, prefix, tp)
• find_all_results(self)
• find_all_results_with_text(self)

Incorrect argument names

Method	Actual Name	Documented Name	Notes
set_read_only	read_only	value
set_scratch	scratch	value
set_encoding	encoding_name	encoding
set_line_endings	line_ending_name	line_endings
insert	pt	point
insert	text	string
erase	r	region
replace	r	region
replace	text	string
run_command	cmd	string
substr	x	region or point
find	start_pt	start_point
find_all	fmt	format
extract_scope	pt	point
scope_name	pt	point
match_selector	pt	point
score_selector	pt	point
style_for_scope	scope	scope_name
line	x	region or point
full_line	x	region or point
word	x	region or point
classify	pt	point
find_by_class	pt	point
expand_by_class	x	region or point
rowcol	tp	point
show	x	location
show	show_surrounds		What does this do?
show_at_center	x	location
set_viewport_position	xy
set_viewport_position	animate		typo: <animate<
text_to_layout	tp	point
text_to_window	tp	point
layout_to_text	xy	vector
layout_to_window	xy	vector
window_to_layout	xy	vector
window_to_text	xy	vector
fold	x	region or [regions]
unfold	x	region or [regions]
command_history	delta	index
set_overwrite_status	value	enabled
show_popup_menu	on_select	on_done

Phantom

Undocumented methods

• __eq__(self, rhs)

PhantomSet

Undocumented methods

• __del__(self)

Incorrect argument names

Method	Actual Name	Documented Name	Notes
__init__	key		Optional, defaults to "".
update	new_phantoms	phantoms

[jrappen]

Also related: #2146

[OdatNurd]

In a similar vein, see #1883 w/regards to the documented return value of the description method of all of the command classes potentially being wrong.

[titoBouzout]

@wbond it would be nice to have some (at least) of this undocumented stuff on the official documentation, took me a while to understand why view.run_command('close') wasnt working and to notice there's an undocumented method view.close()

[Cerberus-tm]

Very interesting! Now I wonder how wise it would be to use those undocumented functions/methods in a plug-in: might they be retracted or changed in future versions of Sublime? Some look very nice, though...

[FichteFoll]

Many of these are in use by plugins and I suspect its unlikely for them to be removed without notice, maybe excluding those that already have been deprecated.

The next big release of ST specifically aims to keep compatibility where possible.

[jrappen]

Also related: #2905

[jrappen]

Also related: #2691