Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

testing: leading spaces in Example output are dropped from godoc display #4487

Closed
rsc opened this issue Dec 4, 2012 · 13 comments
Closed

testing: leading spaces in Example output are dropped from godoc display #4487

rsc opened this issue Dec 4, 2012 · 13 comments
Labels
FrozenDueToAge Suggested Issues that may be good for new contributors looking for work to do.
Milestone

Comments

@rsc
Copy link
Contributor

rsc commented Dec 4, 2012

If you write an example that generates a right-leaning triangle:

// Output:
//   *
//  **
// ***

Then it tests okay (I think the leading space is dropped from the target and the actual
output)
but it formats in the web godoc as:

*
 **
***

instead of

  *
 **
***

That is, godoc eats the leading spaces.

More generally I wonder if the comment processing in examples should be handed off to
the standard go/doc comment processing and formatting. It already handles stripping an
*equal* amount of indent from pre blocks.
@rsc
Copy link
Contributor Author

rsc commented Dec 10, 2012

Comment 1:

Labels changed: added size-m.

@rsc
Copy link
Contributor Author

rsc commented Dec 10, 2012

Comment 2:

Labels changed: added suggested.

@cespare
Copy link
Contributor

cespare commented Jan 5, 2013

Comment 3:

This behavior is inherent to the Example parsing in go/doc -- it calls strings.TrimSpace
on Output.
This seems wrong to me not only for the purposes of displaying the Example but for
testing as well. One might well construct a whitespace-sensitive example that doesn't
fail as expected; for instance, the following actual outputs are accepted by the
right-leaning triangle example output:
*
 **
***
         *
 **
***
The testing documentation isn't explicit about the behavior here. What if the output
parsing were changed? Right now, doc.Examples removes all leading/trailing whitespace;
what if instead it only removed /^[ ]*\n?/   ? I think that's a more intuitive behavior
that works for both the single-line (e.g., '// Output: hi') and multi-line output
targets.
The trimming of the actual output would have to be adjusted correspondingly.
I'm happy to make these changes but wanted some feedback first.

@cespare
Copy link
Contributor

cespare commented Jan 5, 2013

Comment 4:

@rsc regarding your suggestion about handing off the comment processing -- is stripping
equal whitespace from the front of the output block desirable?

@agl
Copy link
Contributor

agl commented Jan 6, 2013

Comment 5:

I'm guessing that rsc intended to assign this to Andrew instead.

Owner changed to @adg.

@rsc
Copy link
Contributor Author

rsc commented Jan 6, 2013

Comment 6:

Indeed, sorry.

@cespare
Copy link
Contributor

cespare commented Jan 6, 2013

Comment 7:

* Does an issue having an owner imply "don't work on this"?
* According to http://swtch.com/~rsc/go11.html, the 'Suggested' label is "suggested for
people looking for work"
Thanks for the clarification; this is not covered in
http://golang.org/doc/contribute.html.

@rsc
Copy link
Contributor Author

rsc commented Jan 6, 2013

Comment 8:

Unless the issue status is Started or a comment by someone says
they're working on it, then it's up for grabs. Thanks.
Stripping equal whitespace seems fine and required. Otherwise you'd
have to write
//line1
//line2
instead of
// line1
// line2

@cespare
Copy link
Contributor

cespare commented Jan 6, 2013

Comment 9:

Thanks Russ.
Sorry I wasn't clear -- I was talking about pre block rule where any equal amount of
leading whitespace is stripped.
Removing the single space from the front is of course fine and is already taken care of
by the normal comment parsing before doc.Examples gets to it.

@rsc
Copy link
Contributor Author

rsc commented Jan 6, 2013

Comment 10:

Can you give an example? I'm surprised that normal comment parsing
strips the space; otherwise how can it distinguish //foo from // foo?

@cespare
Copy link
Contributor

cespare commented Jan 6, 2013

Comment 11:

This is what the docs for (*CommentGroup) Text() in go/ast indicate.
"Comment markers (//, /*, and */), the first space of a line comment, and leading and
trailing empty lines are removed."
Here's an example: http://play.golang.org/p/PWA4tmcnOe

@adg
Copy link
Contributor

adg commented Jan 7, 2013

Comment 12:

This is merely the result of some over-aggressive trimming. The fix is simple:
https://golang.org/cl/7057048/

Status changed to Started.

@adg
Copy link
Contributor

adg commented Jan 7, 2013

Comment 13:

This issue was closed by revision a88bbbb.

Status changed to Fixed.

@rsc rsc added fixed Suggested Issues that may be good for new contributors looking for work to do. labels Jan 7, 2013
@rsc rsc assigned adg Jan 7, 2013
@rsc rsc added this to the Go1.1 milestone Apr 14, 2015
@rsc rsc removed the go1.1 label Apr 14, 2015
@golang golang locked and limited conversation to collaborators Jun 24, 2016
@rsc rsc unassigned adg Jun 22, 2022
This issue was closed.
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
FrozenDueToAge Suggested Issues that may be good for new contributors looking for work to do.
Projects
None yet
Development

No branches or pull requests

5 participants