js: Point to new location of Interface conversion details. #623
Conversation
| @@ -73,7 +73,7 @@ func (o *Object) Uint64() uint64 { return o.object.Uint64() } | |||
| // Float returns the object converted to float64 according to JavaScript type conversions (parseFloat). | |||
| func (o *Object) Float() float64 { return o.object.Float() } | |||
|
|
|||
| // Interface returns the object converted to interface{}. See GopherJS' README for details. | |||
| // Interface returns the object converted to interface{}. See table in package comment for details. | |||
There was a problem hiding this comment.
Would "package documentation" be better? Still approved.
There was a problem hiding this comment.
I'm worried that "package documentation" would mean all of the documentation, it's not very specific.
I wanted to refer to the package comment – the comment on package declaration – which is just the top-most section of package documentation, where the table is contained.
From https://blog.golang.org/godoc-documenting-go-code:
Comments on package declarations should provide general package documentation. These comments can be short, like the sort package's brief description:
// Package sort provides primitives for sorting slices and user-defined // collections. package sortThey can also be detailed like the gob package's overview. That package uses another convention for packages that need large amounts of introductory documentation: the package comment is placed in its own file, doc.go, which contains only those comments and a package clause.
When writing package comments of any size, keep in mind that their first sentence will appear in godoc's package list.
Emphasized relevant phrases used. What do you think?
There was a problem hiding this comment.
@neelance Ping. Is the above convincing enough?
There was a problem hiding this comment.
It's been a few days, and I still haven't heard back on my comment above. Since this has approval, I'll assume it's convincing and merge this in order to make progress.
If there's anything that can be improved or needs to be followed up, another PR can be made.
When the "See GopherJS' README for details." phrase was added in 88f12aa, the JavaScript <-> Go conversion table was in README. It was moved in c6e849f to the package comment of
jspackage.Fixes #622.