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

Comments

Projects
None yet
5 participants
@rsc
Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor Author

commented Dec 10, 2012

Comment 1:

Labels changed: added size-m.

@rsc

This comment has been minimized.

Copy link
Contributor Author

commented Dec 10, 2012

Comment 2:

Labels changed: added suggested.

@cespare

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor

commented Jan 6, 2013

Comment 5:

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

Owner changed to @adg.

@rsc

This comment has been minimized.

Copy link
Contributor Author

commented Jan 6, 2013

Comment 6:

Indeed, sorry.
@cespare

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor Author

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

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor Author

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

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor

commented Jan 7, 2013

Comment 13:

This issue was closed by revision a88bbbb.

Status changed to Fixed.

@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

This issue was closed.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.