Skip to content

Commit 26df454

Browse files
gh-138772: Improve documentation for turtle color functions
Use multiple signatures for clarity. Explain different forms of bgcolor() in details.
1 parent e9c538d commit 26df454

File tree

1 file changed

+41
-11
lines changed

1 file changed

+41
-11
lines changed

Doc/library/turtle.rst

Lines changed: 41 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -777,13 +777,17 @@ Turtle motion
777777
180.0
778778

779779

780-
.. function:: dot(size=None, *color)
780+
.. function:: dot()
781+
dot(size)
782+
dot(color, /)
783+
dot(size, color, /)
784+
dot(size, r, g, b, /)
781785

782786
:param size: an integer >= 1 (if given)
783787
:param color: a colorstring or a numeric color tuple
784788

785789
Draw a circular dot with diameter *size*, using *color*. If *size* is
786-
not given, the maximum of pensize+4 and 2*pensize is used.
790+
not given, the maximum of ``pensize+4` and ``2*pensize`` is used.
787791

788792

789793
.. doctest::
@@ -1152,7 +1156,9 @@ Drawing state
11521156
Color control
11531157
~~~~~~~~~~~~~
11541158

1155-
.. function:: pencolor(*args)
1159+
.. function:: pencolor()
1160+
pencolor(color, /)
1161+
pencolor(r, g, b, /)
11561162

11571163
Return or set the pencolor.
11581164

@@ -1161,7 +1167,7 @@ Color control
11611167
``pencolor()``
11621168
Return the current pencolor as color specification string or
11631169
as a tuple (see example). May be used as input to another
1164-
color/pencolor/fillcolor call.
1170+
color/pencolor/fillcolor/bgcolor call.
11651171

11661172
``pencolor(colorstring)``
11671173
Set pencolor to *colorstring*, which is a Tk color specification string,
@@ -1201,7 +1207,9 @@ Color control
12011207
(50.0, 193.0, 143.0)
12021208

12031209

1204-
.. function:: fillcolor(*args)
1210+
.. function:: fillcolor()
1211+
fillcolor(color, /)
1212+
fillcolor(r, g, b, /)
12051213

12061214
Return or set the fillcolor.
12071215

@@ -1210,7 +1218,7 @@ Color control
12101218
``fillcolor()``
12111219
Return the current fillcolor as color specification string, possibly
12121220
in tuple format (see example). May be used as input to another
1213-
color/pencolor/fillcolor call.
1221+
color/pencolor/fillcolor/bgcolor call.
12141222

12151223
``fillcolor(colorstring)``
12161224
Set fillcolor to *colorstring*, which is a Tk color specification string,
@@ -1244,7 +1252,10 @@ Color control
12441252
(255.0, 255.0, 255.0)
12451253

12461254

1247-
.. function:: color(*args)
1255+
.. function:: color()
1256+
color(color, /)
1257+
color(r, g, b, /)
1258+
color(pencolor, fillcolor, /)
12481259

12491260
Return or set pencolor and fillcolor.
12501261

@@ -1870,13 +1881,32 @@ Most of the examples in this section refer to a TurtleScreen instance called
18701881
Window control
18711882
--------------
18721883

1873-
.. function:: bgcolor(*args)
1884+
.. function:: bgcolor()
1885+
bgcolor(color, /)
1886+
bgcolor(r, g, b, /)
18741887

1875-
:param args: a color string or three numbers in the range 0..colormode or a
1876-
3-tuple of such numbers
1888+
Return or set the background color of the TurtleScreen.
18771889

1890+
Four input formats are allowed:
1891+
1892+
``bgcolor()``
1893+
Return the current background color as color specification string or
1894+
as a tuple (see example). May be used as input to another
1895+
color/pencolor/fillcolor/bgcolor call.
1896+
1897+
``bgcolor(colorstring)``
1898+
Set the background color to *colorstring*, which is a Tk color
1899+
specification string, such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.
18781900

1879-
Set or return background color of the TurtleScreen.
1901+
``bgcolor((r, g, b))``
1902+
Set the background color to the RGB color represented by the tuple of
1903+
*r*, *g*, and *b*.
1904+
Each of *r*, *g*, and *b* must be in the range 0..colormode, where
1905+
colormode is either 1.0 or 255 (see :func:`colormode`).
1906+
1907+
``bgcolor(r, g, b)``
1908+
Set the background color to the RGB color represented by *r*, *g*, and *b*. Each of
1909+
*r*, *g*, and *b* must be in the range 0..colormode.
18801910

18811911
.. doctest::
18821912
:skipif: _tkinter is None

0 commit comments

Comments
 (0)