[GitHub] [beam] damccorm opened a new issue, #20341: Improve beam package GoDoc with examples.

[GitBox <gi...@apache.org>]

damccorm opened a new issue, #20341:
URL: https://github.com/apache/beam/issues/20341

   The  [beam package godoc](https://godoc.org/github.com/apache/beam/sdks/go/pkg/beam?utm_source=backtogodoc) needs some improvements.
   @lostluck wrote some for internal use at Google, but it hasn't yet migrated out. 
   Even without these, godoc provides a few nice functions like [compileable examples](https://blog.golang.org/examples) and [more](https://pkg.go.dev/github.com/fluhus/godoc-tricks?tab=doc) of which we have made light use.
   
   Given the complexity of the API, we could use more. 
   
   In particular, calling out the Bundle Lifecycle method names for Structural DoFns, and the method names for Structural CombineFns would be of immense value, as that's not clearly documented.
   
   Also, examples of how to use GroupByKey and CoGroupByKey and what that means for the subsequent DoFn methods, and how they affect Side Inputs.
   
   As examples are run during tests, this will also improve testing of various edge cases, to be part of the package. 
   
   The main complication is that these will require _example.go files since methods cannot be added to types in function scopes.
   
   Imported from Jira [BEAM-10253](https://issues.apache.org/jira/browse/BEAM-10253). Original Jira may contain additional context.
   Reported by: lostluck.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@beam.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [beam] lostluck commented on issue #20341: Improve beam package GoDoc with examples.

[GitBox <gi...@apache.org>]

lostluck commented on issue #20341:
URL: https://github.com/apache/beam/issues/20341#issuecomment-1159159352

   Go 1.19 will support "lists" and "links" including references to other sections of the doc, and other package docs.
   
   https://tip.golang.org/doc/comment#lists
   https://tip.golang.org/doc/comment#links
   
   Links especially will dramatically simplify cleaning up the go doc, and properly documenting the SDK in the SDK going forward.
   
   We can start using these new specifications immeadiately, they simply won't be displayed correctly until pkg.go.dev is using go 1.19.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@beam.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org