xtractdoc

README

xtractdoc

xtractdoc is a little tool to extract identifiers from Go source code and their according documentation.

why would one ever need that?

For example, if you want to create a single source of truth for your documentation, but you need that in other places, like e.g. using that in a $ref description in an OpenAPI specification.

usage

go install github.com/worldiety/xtractdoc/cmd/xtractdoc@latest
xtractdoc -modPath=/my/go/module -format=yaml -packages="github.com/worldiety/xtractdoc/testdata;github.com/worldiety/xtractdoc/testdata/v1" -pkgSep=- > godoc.yaml

Example output:

# Code generated by github.com/worldiety/xtractdoc DO NOT EDIT.

readme: "# xtractdoc\n\nxtractdoc is a little tool to extract identifiers from Go source code and their according documentation.\n\n## why would one ever need that?\n\nFor example, if you want to create a single source of truth for your documentation, but you need that\nin other places, like e.g. using that in a _$ref_ description in an OpenAPI specification.\n\n## usage\n\n```bash\ngo install github.com/worldiety/xtractdoc/cmd/xtractdoc@latest\nxtractdoc -modPath=/my/go/module -format=yaml -packages=\"github.com/worldiety/xtractdoc/testdata;github.com/worldiety/xtractdoc/testdata/v1\" -pkgSep=- > godoc.yaml\n```\n\nExample output:\n\n```yaml\n \n```"
module: github.com/worldiety/xtractdoc
packages:
  github.com-worldiety-xtractdoc-testdata:
    readme: test readme
    doc: |
      Package testdata is about testing.
    name: testdata
    imports:
      - github.com-worldiety-xtractdoc-testdata-v1
    types:
      Behavior:
        doc: |
          A Behavior is what to want.
        baseType: interface
      Entity:
        doc: |
          An Entity to store.
        baseType: struct
        stereotypes:
          - struct
          - class
        factories:
          NewEntity:
            doc: |
              NewEntity is a conventional constructor.
            stereotypes:
              - constructor
            results:
              __0:
                baseType: Entity
                stereotypes:
                  - parameter
                  - out
                  - result
        methods:
          String:
            doc: |
              String returns a human-
              readable representation.

              Second line.
            stereotypes:
              - method
            results:
              __0:
                baseType: string
                stereotypes:
                  - parameter
                  - out
                  - result
        fields:
          Description:
            doc: |
              A Description about the thing.
            baseType: map[string]int
            stereotypes:
              - property
          GenericOne:
            doc: |
              GenericOne is recursive.
            baseType: X[X[chan<-bool]]
            stereotypes:
              - property
          Name:
            doc: |
              A Name to tell about.
            baseType: string
            stereotypes:
              - property
      MyEnum:
        doc: |
          MyEnum is like Go does it.
        baseType: string
        stereotypes:
          - string
          - enum
        enum:
          AConstant:
            doc: |-
              Group documentation on constants.

              AConstant here.
          BConstant:
            doc: |-
              Group documentation on constants.

              BConstant here.
      MyFace:
        baseType: interface
      MyFaceImpl:
        baseType: struct
        stereotypes:
          - struct
          - class
        methods:
          A:
            stereotypes:
              - method
            results:
              __0:
                baseType: other.DifferentV1
                stereotypes:
                  - parameter
                  - out
                  - result
              __1:
                baseType: error
                stereotypes:
                  - parameter
                  - out
                  - result
      X:
        baseType: struct
        stereotypes:
          - struct
          - class
        fields:
          V:
            baseType: T
            stereotypes:
              - property
    consts:
      HelloConst:
        doc: |-
          grouped consts

          HelloConst as const
    vars:
      Hello:
        doc: Hello to the world.
    functions:
      BestFunc:
        doc: |
          The BestFunc is really a static package level function.
  github.com-worldiety-xtractdoc-testdata-v1:
    name: other
    types:
      DifferentV1:
        doc: |
          DifferentV1 shows a struct whose import path is different from its package name.
        baseType: struct
        stereotypes:
          - struct
          - class