Subversion Repositories openrisc

// Copyright 2009 The Go Authors. All rights reserved.

// Use of this source code is governed by a BSD-style

// license that can be found in the LICENSE file.

// Package doc extracts source code documentation from a Go AST.

package doc

import (

        "go/ast"

        "go/token"

)

// Package is the documentation for an entire package.

type Package struct {

        Doc        string

        Name       string

        ImportPath string

        Imports    []string

        Filenames  []string

        Bugs       []string

        // declarations

        Consts []*Value

        Types  []*Type

        Vars   []*Value

        Funcs  []*Func

}

// Value is the documentation for a (possibly grouped) var or const declaration.

type Value struct {

        Doc   string

        Names []string // var or const names in declaration order

        Decl  *ast.GenDecl

        order int

}

// Type is the documentation for a type declaration.

type Type struct {

        Doc  string

        Name string

        Decl *ast.GenDecl

        // associated declarations

        Consts  []*Value // sorted list of constants of (mostly) this type

        Vars    []*Value // sorted list of variables of (mostly) this type

        Funcs   []*Func  // sorted list of functions returning this type

        Methods []*Func  // sorted list of methods (including embedded ones) of this type

}

// Func is the documentation for a func declaration.

type Func struct {

        Doc  string

        Name string

        Decl *ast.FuncDecl

        // methods

        // (for functions, these fields have the respective zero value)

        Recv  string // actual   receiver "T" or "*T"

        Orig  string // original receiver "T" or "*T"

        Level int    // embedding level; 0 means not embedded

}

// Mode values control the operation of New.

type Mode int

const (

        // extract documentation for all package-level declarations,

        // not just exported ones

        AllDecls Mode = 1 << iota

        // show all embedded methods, not just the ones of

        // invisible (unexported) anonymous fields

        AllMethods

)

// New computes the package documentation for the given package AST.

// New takes ownership of the AST pkg and may edit or overwrite it.

//

func New(pkg *ast.Package, importPath string, mode Mode) *Package {

        var r reader

        r.readPackage(pkg, mode)

        r.computeMethodSets()

        r.cleanupTypes()

        return &Package{

                Doc:        r.doc,

                Name:       pkg.Name,

                ImportPath: importPath,

                Imports:    sortedKeys(r.imports),

                Filenames:  r.filenames,

                Bugs:       r.bugs,

                Consts:     sortedValues(r.values, token.CONST),

                Types:      sortedTypes(r.types, mode&AllMethods != 0),

                Vars:       sortedValues(r.values, token.VAR),

                Funcs:      sortedFuncs(r.funcs, true),

        }

}