ドキュメントとソースコードの対応

ソフトウェア開発においてドキュメントとソースコードの対応を取り続けることは想像以上に難しい。開発当初は綺麗に対応していたドキュメントとソースが年を追うごとに乖離していき、それぞれ別物として成長していくことはよくある光景である。そのような中、ドキュメントに対応するソースが何であるか一覧化できるそりゅ~しょんが強く求められている・・・ような気がする。

ざっくり言うとドキュメントとソースコードの紐付けが自動でできるかどうか気になったのでやってみた。(ここにはひさしぶりの投稿)

条件は下記の通り。

  • Postgresql9.3.4のマニュアルに対応するソースを表示する。
  • マニュアル、ソースそれぞれについて出てくる単語を抽出し、TF-IDFで重み付けを行い、コサイン類似度の大きなものを関連しているとみなす。

結果、英語版のマニュアルとソースの対応はそこそこの精度で取れるが、日本語版のマニュアルに対する対応はイマイチだった。ソース中に日本語が入っているとは思えない(=キーとなる情報が少ない)ので納得のいく結果ではある。

下記はcreateuserとindex-introの例。[]内には–・・・.html(マニュアル)–に対して類似度が大きなソース上位5つが入っている。()内の”の中がソースコードの名称でその後の数字がコサイン類似度。なお、htmlディレクトリ以下にあるのが英語版で、html-ja以下にあるのが日本語版となっている。

--../data/postgresql-9.3.4/doc/src/sgml/html/app-createuser.html--
[   (   '../data/postgresql-9.3.4/src/bin/scripts/createuser.c',
        0.5315036131957114),
    (   '../data/postgresql-9.3.4/src/backend/commands/user.c',
        0.49634873213501424),
    (   '../data/postgresql-9.3.4/src/bin/pg_dump/pg_dumpall.c',
        0.45199746892518794),
    (   '../data/postgresql-9.3.4/src/include/commands/user.h',
        0.4456889634461926),
    (   '../data/postgresql-9.3.4/src/include/catalog/pg_authid.h',
        0.436479878362433)]

--../data/postgresql-9.3.4/html-ja/app-createuser.html--
[   (   '../data/postgresql-9.3.4/src/bin/scripts/createuser.c',
        0.24660267524744783),
    (   '../data/postgresql-9.3.4/src/bin/psql/tab-complete.c',
        0.21638658446826328),
    (   '../data/postgresql-9.3.4/src/backend/commands/user.c',
        0.18185439320172517),
    (   '../data/postgresql-9.3.4/src/backend/catalog/objectaddress.c',
        0.17654887868713476),
    (   '../data/postgresql-9.3.4/src/backend/parser/gram.c',
        0.15892817112702087)]
--../data/postgresql-9.3.4/doc/src/sgml/html/indexes-intro.html--
[   (   '../data/postgresql-9.3.4/src/backend/commands/indexcmds.c',
        0.5887593627491802),
    ('../data/postgresql-9.3.4/src/include/utils/rel.h', 0.5847988052787634),
    (   '../data/postgresql-9.3.4/src/backend/optimizer/path/indxpath.c',
        0.5736868945937168),
    (   '../data/postgresql-9.3.4/src/backend/catalog/index.c',
        0.5695396670614502),
    (   '../data/postgresql-9.3.4/src/backend/optimizer/util/plancat.c',
        0.5669650556082131)]

--../data/postgresql-9.3.4/html-ja/indexes-intro.html--
[   (   '../data/postgresql-9.3.4/src/backend/lib/stringinfo.c',
        0.09184457364491616),
    (   '../data/postgresql-9.3.4/src/interfaces/ecpg/test/expected/sql-insupd.c',
        0.0886416204237675),
    (   '../data/postgresql-9.3.4/src/test/examples/testlibpq3.c',
        0.08837346944289427),
    (   '../data/postgresql-9.3.4/src/backend/access/heap/visibilitymap.c',
        0.08815864541352804),
    (   '../data/postgresql-9.3.4/src/interfaces/ecpg/test/expected/sql-indicators.c',
        0.08800994862677734)]

詳細な結果はhttp://staka.jp/doc-src/result.txtの通り。なんとなくだが、英語版マニュアルとソースコードはそれなりに紐付いているように見える。日本語のコメントが豊富にあるソースとであれば日本語版もうまく行くような気がしないでもない。

ソースコードはhttps://github.com/s-taka/doc-srcにおいておいた。基本的にPythonで書いていて、日本語マニュアルの形態素解析はMeCabで行っている。最近流行のword2vecの利用は今後の課題。

補記

前回同様、前段の補記。ドキュメントとソースが乖離していくのがよくある光景なのは事実だが、ドキュメントとソースが(ざっくりと)紐付いてうれしい人がどれだけいるかは謎。ドキュメント→ソース→コミットログ→作成者とたどっていけるのはある程度便利かもしれないが。本当は、ドキュメントとソースの乖離が分かるとうれしい人は多そうだけど、自然言語処理のアプローチでそれを見つけるのは至難の技だろーなーと思う。

 

Leave a Comment


NOTE - You can use these HTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>