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

doc: comment all public symbols #9

Closed
mmcloughlin opened this Issue Dec 31, 2018 · 4 comments

Comments

2 participants
@mmcloughlin
Copy link
Owner

mmcloughlin commented Dec 31, 2018

  • (root)
  • build
  • buildtags
  • gotypes
  • operand
  • pass
  • printer
  • reg
  • src
  • x86
  • internal/cmd/avogen
  • internal/gen
  • internal/inst
  • internal/load
  • internal/opcodescsv
  • internal/opcodesxml
  • internal/prnt
  • internal/stack
  • internal/test
  • package-level doc comments

Once done, enable public doc linting. Unfortunately this will require a workaround for golangci/golangci-lint#21.

@mmcloughlin mmcloughlin added this to the Initial Release milestone Dec 31, 2018

@mmcloughlin mmcloughlin added the cleanup label Jan 2, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 5, 2019

mmcloughlin added a commit that referenced this issue Jan 6, 2019

mmcloughlin added a commit that referenced this issue Jan 6, 2019

@mmcloughlin

This comment has been minimized.

Copy link
Owner

mmcloughlin commented Jan 6, 2019

A little helper for package doc strings (ref):

$ go list -f '{{.ImportPath}}: {{.Doc}}' ./...
github.com/mmcloughlin/avo:
github.com/mmcloughlin/avo/build:
github.com/mmcloughlin/avo/buildtags: Package buildtags provides types for representing and manipulating build constraints.
github.com/mmcloughlin/avo/examples/add:
github.com/mmcloughlin/avo/examples/args:
github.com/mmcloughlin/avo/examples/complex:
github.com/mmcloughlin/avo/examples/data:
github.com/mmcloughlin/avo/examples/dot:
github.com/mmcloughlin/avo/examples/fnv1a:
github.com/mmcloughlin/avo/examples/geohash:
github.com/mmcloughlin/avo/examples/greet:
github.com/mmcloughlin/avo/examples/returns:
github.com/mmcloughlin/avo/examples/sha1:
github.com/mmcloughlin/avo/examples/stadtx: Package stadtx implements Stadtx Hash https://github.com/demerphq/BeagleHash
github.com/mmcloughlin/avo/examples/sum:
github.com/mmcloughlin/avo/gotypes: Package gotypes provides helpers for interacting with Go types within avo functions.
github.com/mmcloughlin/avo/internal/cmd/adhoc:
github.com/mmcloughlin/avo/internal/cmd/avogen: Command avogen generates code based on the instruction database.
github.com/mmcloughlin/avo/internal/gen:
github.com/mmcloughlin/avo/internal/inst:
github.com/mmcloughlin/avo/internal/load:
github.com/mmcloughlin/avo/internal/opcodescsv:
github.com/mmcloughlin/avo/internal/opcodesxml:
github.com/mmcloughlin/avo/internal/prnt:
github.com/mmcloughlin/avo/internal/stack:
github.com/mmcloughlin/avo/internal/test:
github.com/mmcloughlin/avo/operand:
github.com/mmcloughlin/avo/pass: Package pass implements processing passes on avo Files.
github.com/mmcloughlin/avo/printer: Package printer implements printing of avo files in various formats.
github.com/mmcloughlin/avo/reg:
github.com/mmcloughlin/avo/src: Package src provides types for working with source files.
github.com/mmcloughlin/avo/tests/cast:
github.com/mmcloughlin/avo/tests/textflag:
github.com/mmcloughlin/avo/x86:

mmcloughlin added a commit that referenced this issue Jan 6, 2019

@mmcloughlin

This comment has been minimized.

Copy link
Owner

mmcloughlin commented Jan 6, 2019

Calling this done, since the linter isn't complaining any more. However there are still undocumented symbols under generated code that we could look at cleaning up.

@mmcloughlin mmcloughlin closed this Jan 6, 2019

@dgryski

This comment has been minimized.

Copy link
Collaborator

dgryski commented Jan 6, 2019

"Human-written code is held to a higher standard than machine-written code."

@mmcloughlin

This comment has been minimized.

Copy link
Owner

mmcloughlin commented Jan 6, 2019

"Human-written code is held to a higher standard than machine-written code."

In this case I think the only valuable place to add generated documentation is the instruction database. We can just duplicate the comments in the x86 package to the corresponding functions under build.

avo/x86/zctors.go

Lines 12 to 22 in 602bb51

// ADCB: Add with Carry.
//
// Forms:
//
// ADCB imm8 al
// ADCB imm8 r8
// ADCB r8 r8
// ADCB m8 r8
// ADCB imm8 m8
// ADCB r8 m8
func ADCB(imr, amr operand.Op) (*avo.Instruction, error) {

This is covered by #36.

mmcloughlin added a commit that referenced this issue Jan 6, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment