Talk:Docstring

Python PEP 292 Template strings

Recently, a contributor removed all reference to PEP 292 template strings from this article. That did not seem appropriate at all, so I reverted the removal. PEP 292 specifies a method for including string literals in Python code, and is routinely used in conjunction with Docstring syntax. This is a formal request for clarification for why this content was removed. Thanks. dr.ef.tymac 00:50, 23 May 2007 (UTC)

I removed all mention of PEP 292 as it is definitely about string interpolation rather than docstrings. PEP 292 does not add any new string literal syntax. It describes a way of creating one string from another when that other string embeds references to the values of names.

PEP 292 does not mention docstrings at all.

Python syntax does not allow using template expressions as a docstring literal, (however an objects __doc__ attribute may be manipulated in many ways).

There is a lot of Python that 'can be used with docstrings' but the article is focused on docstrings. In fact PEP 292 is just another feature of Python. Please give examples of why it should be included. --Paddy 07:04, 23 May 2007 (UTC)

Ok then, Paddy, I see you are applying a very strict distinction based on the syntax specification of Python itself. Fair enough. I can see how that might be viewed as unacceptably imprecise by some readers. Although, I must say that I do not agree that such a rigidly applied standard should serve as the baseline for absolute exclusion of content from this article (you yourself have [implicitly] acknowledged that PEP 292 'can be used with docstrings'). If there are other relevant uses for docstrings within Python (as you and I both know there are) and they are verifiable, citable, and established, I'd also favor inclusion of those uses as well.

Nevertheless, although I do not agree that such a rigid standard of inclusion should apply, I also don't have any desire to engage in language-lawyering nitpickery either. Therefore, as a compromise, I will comment out the (in your apparent view) offending sections until such time as: 1) this article is further expanded to include relevant uses of docstrings, besides just PEP 292; or 2) you or any other contributor credibly disputes this proposed compromise.

I see absolutely no harm in mentioning established ancillary language features in any context whenever relevant, and whenever likely to expand the content and breadth of an Encyclopedia article. Having said that, my proposed compromise seems appropriate, so I will implement it now. If you disagree please let me know, if not, good day. dr.ef.tymac 13:33, 23 May 2007 (UTC)

Hi Dreftymac, i realy am curious as to why PEP 292 is associated with docstrings. I've read the PEP. Please enlighten me with examples. --Paddy 17:17, 23 May 2007 (UTC)

As you've already indicated, PEP 292 is associated with variable substitution, so technically, there is no "direct association" under a strict reading of the spec. Nevertheless, a PEP 292 Template may require a string literal that spans more than one physical line of source code, which is obviously most easily done in Python with docstring syntax. (See here for an example in Python source code.)

The question hinges on how loosely one defines "associated" ... some may consider my definition was too broad, given that there were no other example uses of docstrings in the article, which is why I commented the content out. dr.ef.tymac 21:12, 23 May 2007 (UTC)

(Note: I do find it a little inconsistent that we should have to delete all reference to PEP 292, when the article still contains the section "Tools using docstrings") ... but as I indicated, I really have no desire to quibble over this. dr.ef.tymac 21:17, 23 May 2007 (UTC)

Hi again Draftymac, looking at your example in Python source code, I wonder if a source of our confusion could be terminology? Your code example shows the use of a triple quoted string literal, but not the use of a docstring. A docstring is a string literal appearing as the first statement of a function/method, class, or module. The string literal can be single quoted or triple quoted, but most usually appears triple quoted. So, we might not be at odds on this, PEP 292 might be appropriate in an article on triple quoted strings, but triple quoted strings are not always docstrings, and docstrings cannot be expressions returning a string, hence my earlier comments.

Here is a console session that might help

PythonWin 2.5 (r25:51908, Sep 19 2006, 09:52:17) [MSC v.1310 32 bit (Intel)] on win32.
Portions Copyright 1994-2006 Mark Hammond - see 'Help/About PythonWin' for further copyright information.
>>> from string import Template
>>> s = Template('${name} was born in ${country}')
>>> def f():
... 	s.substitute(name='Guido', country='the Netherlands')
... 	pass
... 
>>> def g():
... 	'A docstring needs to be a string literal'
... 	pass
... 
>>> f()
>>> g()
>>> f.__doc__
>>> g.__doc__
'A docstring needs to be a string literal'
>>> def h():
... 	"""A docstring as
... 	a triple-quoted
... 	string literal
... 	"""
... 	pass
... 
>>> h.__doc__
'A docstring as\n\ta triple-quoted\n\tstring literal\n\t'
>>> print h.__doc__
A docstring as
	a triple-quoted
	string literal
	
>>> 

--Paddy 05:01, 24 May 2007 (UTC)

Yes. You are exactly right. I should clarify, the reason this article exists at all was because some WP contributors got into a dispute over how "triple-quoted docstrings" (in the correct sense of the term you indicate) can sometimes also be considered as a ("kind of") "multi-line comments" ... but then the distinction came up that "triple-quoted string literals" can also be used as "multi-line comments" in general (in which a string literal is specified in sourcecode, but not assigned to a variable, and not used for the __doc__ property of a specific function or class).

This article was created as a kind of "dumping ground" to deal with all these different (and admittedly sloppy) interpretations for uses of the 'triple quoted string literal' ... and the word "Docstring" was used (again, sloppily) as an umbrella term for all of them. At least that's how I remember the progression. Of course, in Python, this is a very flagrant abuse of terminology. So you've pointed out a very significant issue here. In discussing this article, I had brought along my personal recollection of how it got started, but most readers will not know or care about that, thus harming the accuracy of the article and its consistency with Python conventions.

In light of that, I can see all the more clearly now why you deleted that. Thanks, I agree with your clarification. dr.ef.tymac 17:00, 24 May 2007 (UTC)

This article could use some review for accuracy

Recently, a contributor brought up a good point that the word "Docstring" has specific meaning in Python, and that meaning may not be entirely consistent with the original reason for why this article was created (to talk about "docstring" in the vague sense of "programming in general" ... whatever that means).

Consequently, it may be appropriate to clarify this article to talk about Python specifically, or to otherwise address the problems that may arise from varying notions about what this term actually means, and what this article is supposed to be about (so far all I see are python and lisp). dr.ef.tymac 17:08, 24 May 2007 (UTC)

source tree?

"docstrings are not stripped from the source tree when it is parsed"

Who should one understand the term source tree? Thanks, --Abdull (talk) 19:04, 18 February 2010 (UTC)

Languages with missing citations

I removed the R and Clojure languages because a mention/citation of docstrings could not be found in a long time. It looks as if they don't have the capability and so should be removed. --Paddy (talk) 20:17, 19 August 2010 (UTC)

Content of Python docstrings

This section seems overlong, and provides no references for its assertions. Surely we are better to say simply that "there are common conventions", and point to "PEP 257 -- Docstring Conventions"? Snori (talk) 03:12, 29 December 2016 (UTC)

Metadata

The link to metadata in the intro paragraph is not helpful, it links to a very general concept of metadata whereas someone reading this article might expect specifically metadata as it pertains to helping users understand programming functions. 2A02:3032:9:FBB3:C54F:E6BF:66CD:B1AE (talk) 21:14, 28 May 2022 (UTC)