Go 언어 습작: 짧고 길어 보이는 GoDoc으로 가는 길

7677 단어 Gogodoc

앞말


이 글은 여기는 저장소입니다. 코드를 샘플로 사용합니다.
또한 다음 환경에서 동작 확인을 진행했다.
OS: CentOS 7.5
Go 언어: 버전 1.9.4(yum에 설치)

GoDoc 개요


다른 언어에도 있는 것처럼 Go 언어도 원본 코드에 적힌 댓글을 바탕으로 합니다.
정의된 문서를 자동으로 생성하는 구조가 준비되어 있습니다.
예를 들어, 만약 당신이 이렇게 평론을 쓴다면...

// チャットプログラムパッケージ
package chat

import (
    "net"
    "fmt"
)

// Observer: メッセージオブザーバを意味する構造体。
type Observer struct {
    Senders []Sender // チャット参加メンバ
    Subject <-chan Notification // 通知受信用チャンネル
}

// WaitNotice: 通知受信関数。
//
// 何らかの通知(Notification)を受け取り, 通知種別に合わせて参加メンバ(Senders)へのメッセージ配信
// あるいは参加メンバの追加削除を行う。
func (observer Observer) WaitNotice() {
    // 通知
    notice := <-observer.Subject

    switch notice.Type {
    case Message:
        // メッセージの配信
        for i := range observer.Senders {
            observer.Senders[i].SendMessage(notice.Message);
        }

        break;

    case Join:
        // メンバーを追加
        observer.Senders = appendSender(notice.ClientId, notice.Connection, observer.Senders);

        fmt.Printf("Client %d join, now menber count is %d\n", notice.ClientId, len(observer.Senders));
        break;

    case Defect:
        // メンバーを削除
        observer.Senders = removeSender(notice.ClientId, observer.Senders);

        fmt.Printf("Client %d defect, now menber count is %d\n", notice.ClientId, len(observer.Senders));
        break;

    default:

    }
}

너는 이런 문서를 만들 수 있다

JavaDoc과 같은 문서 생성 도구에서 주석을 사용하여 표시 등을 제어합니다.
GoDoc은 Markdown처럼 자연스럽게 쓰는 댓글을 일정한 규칙에 따라 진행합니다.
HTML로 변환해야 할 것 같습니다.홀가분했으면 좋겠어요.
하지만 실제로 댓글을 써서 확인하기 전까지는 순조롭게 진행되기 어렵고,
나는 비망록 대신 걸려 넘어진 곳을 쓰고 싶다.

걸림돌


Doc 표시 방법을 몰라요.


Java에서는 SDK 부속 Javadoc 도구를 사용하여 원본 파일에서 문서를 HTML 형식의 파일로 생성할 수 있습니다.
그러면 Go 언어도 go 명령을 사용하여 HTML 파일을 생성하는 것으로 생각했지만 그렇지 않습니다.
고 명령의 도움말로 볼 때, doc라는 하위 명령을 준비했을 수도 있지만, 이것은 이미 추천하지 않습니다
현재 (특히 v1.11 이후) godoc라는 전용 도구를 사용하여 표시합니다.
표시되는 순서는 다음과 같습니다.
1-godoc 가져오기
> go get golang.org/x/tools/cmd/godoc
2 - godoc 서버 프로그램 시작 (포트가 비어 있는 포트임)
> godoc -http=:6060
3 - 브라우저에서 godoc 서버의 지정된 포트에 접근
나는 이렇게 하면 문서를 확인할 수 있다고 생각한다.

자체 제작한 포장을 반영하지 않다


원활하게 문서를 표시할 수 있을 거라 생각했는데 문서에 표시된 포장 일람에
자기가 만든 포장 안 나왔잖아.
하지만 무의식중에 포장 일람표를 보면 Thirdparty라고 적힌 아래의 부분을 찾을 수 있을 것 같습니다.

이 Thirdparty 프로젝트에 표시된 포장 일람은 어디에서 볼 수 있는 구성이라고 생각하지 않습니까?
예, 이 부분의 구성은 GOPATH에서 지정한 디렉터리의 src 이하의 구성과 같습니다.
/home/vagrant/go/src
├── github.com
│   ├── golang
│   │   └── lint
│   ├── kisielk
│   │   ├── errcheck
│   │   └── gotool
│   ├── nsf
│   │   └── gocode
│   └── rogpeppe
│       └── godef
└── golang.org
    └── x
        └── tools

따라서 이 디렉터리에 my.local 라는 디렉터리를 만들고 자체 디렉터리를 이동하면...

문서에 안전하게 반영되었습니다.

전용 함수 표시 안 함


지금까지 나는 이미 조금도 문제가 없다고 생각한다. 아직 조금은 있다.
GoDoc은 공개 함수와 구조체, 비공개 함수와 구조체만 표시합니다.
표시되지 않습니다.
어떻게든 표시하려면 문서의 페이지 URL 끝에 ?m=all 같은 검색 문자열을 입력하십시오
를 추가하여 표시할 수 있습니다.

총결산

  • 문서 작성은 Godoc 도구를 사용하지 않고 브라우저를 통해 진행됨
  • GOPATH 디렉토리 아래에 자체 제작 패키지가 구성되지 않으면 반영되지 않음
  • 개인 함수를 문서에 표시하려면 URL에 "?m=all"
  • 좋은 웹페이지 즐겨찾기