JPH07129381A - プログラムドキュメント作成装置 - Google Patents

Abstract

(57)【要約】 【目的】 高品質なドキュメントを常に得ることができ
るようにする。 【構成】 プログラムファイル記憶装置６から入力した
プログラムを文書データ生成装置２により解析して各要
素に分解し、この解析の結果に基づいて生成した文書デ
ータのテンプレートの内容をユーザが端末装置７を用い
て記述することによって文書データを生成できるように
するとともに、この文書データの要素と上記プログラム
の要素とを比較合成装置４により比較し、全てのプログ
ラムの要素に対応する文書データの要素のみを相互に合
成してドキュメントを作成するようにすることにより、
プログラムの各要素毎にその内容を記述した詳細なドキ
ュメントを常に作成できるようにし、プログラムの内容
を変更した場合には、変更後のプログラムに対応したド
キュメントを作成できるようにして、一定の品質以上の
ドキュメントを常に作成できるようにする。

Description

【発明の詳細な説明】

【０００１】

【産業上の利用分野】本発明は、プログラムドキュメン
ト作成装置に関し、特に、既存のソースプログラムの動
作内容や処理内容などに関するドキュメントを作成する
プログラムドキュメント作成装置に用いて好適なもので
ある。

【０００２】

【従来の技術】従来より、ソフトウェアの開発を行う際
には、ソフトウェアの維持、管理などを容易にするため
に、作成したプログラムの動作／処理内容を記述したド
キュメントを作成することが行われている。そして、既
に作成したプログラムに基づいて、そのプログラムの動
作／処理内容を表すドキュメントを作成する技術が開発
されている。

【０００３】このように、既存のプログラムからその内
容を表すドキュメントを作成するためのシステムとし
て、１つのプログラム中においてプログラムとドキュメ
ントとを１つのファイルとして記述できるようにしたＷ
ＥＢシステムと呼ばれるシステムが知られている。ＷＥ
Ｂシステムは、プログラミング言語と文書整形言語とを
組み合わせたシステムである。

【０００４】図１２は、ＷＥＢシステムで行われる処理
の概略を示す動作説明図である。図１２に示すように、
このＷＥＢシステムにおいては、ＷＥＢ言語で記述した
データをTANGLEと呼ばれるプログラムで処理すると、プ
ログラムのソースコードが得られる。そして、このよう
にして得られたプログラムのソースコードがコンパイラ
にかけられることにより、オブジェクトが生成される。

【０００５】一方、ＷＥＢ言語で記述したデータをWEAV
E と呼ばれるプログラムで処理すると、プログラムのソ
ースコードを含んだドキュメントのソースコードが得ら
れる。そして、このようにして得られたドキュメントの
ソースコードが文書フォーマッタで清書されることによ
り、ドキュメントが生成される。

【０００６】このように、ＷＥＢシステムでは、ＷＥＢ
言語で記述されたデータ中のプログラムコードに相当す
る部分に基づいてオブジェクトが生成され、文書コード
に相当する部分に基づいてドキュメントが生成される。

【０００７】

【発明が解決しようとする課題】しかしながら、上述の
ようなＷＥＢシステムでは、ＷＥＢ言語で記述されたデ
ータ中のプログラムコードに相当する部分と、文書コー
ドに相当する部分とは互いに独立性が非常に高く、両者
は別々に処理されていた。

【０００８】また、上述のようなＷＥＢシステムは、プ
ログラムソースとドキュメントとの関係をチェックする
機構を備えていないため、あるプログラムに対してその
内容とは全く関係のないドキュメントを記述してしまっ
たとしても、その誤りを検出することはできなかった。

【０００９】このため、例えば、プログラムに変数や関
数が新たに加えられた場合や、プログラムから既存の変
数や関数が削除された場合などのように、プログラムの
内容が変更された場合に、このプログラムの変更を反映
したドキュメントが常に得られるとは限らないという問
題があった。

【００１０】また、ＷＥＢ言語でデータを記述するユー
ザごとにそのデータの内容が異なるので、ユーザがＷＥ
Ｂ言語で記述したデータに基づいて生成されるドキュメ
ントの内容もまちまちとなり、一定の品質以上のドキュ
メントが必ずしも得られるとは限らないという問題があ
った。

【００１１】本発明は、このような問題を解決するため
になされたものであり、高品質なドキュメントを常に得
ることができるプログラムドキュメント作成装置を提供
することを目的とする。

【００１２】

【課題を解決するための手段】本発明のプログラムドキ
ュメント作成装置は、入力したプログラムをそのプログ
ラミング言語の文法に従って構文解析し、上記プログラ
ムを種々の要素に分解するプログラム解析手段と、上記
プログラム解析手段により分解されたプログラムの要素
毎に、テンプレート形式で文書を記述することによっ
て、上記プログラムの内容を表す文書データを生成する
文書データ生成手段と、上記文書データをその文法規則
に従って解析し、上記文書データを種々の要素に分解す
る文書データ解析手段と、上記プログラム解析手段によ
り分解されたプログラムの要素と、上記文書データ解析
手段により分解された文書データの要素とを比較し、上
記プログラムの要素に対応する文書データの要素が存在
するか否かを確認する比較手段と、上記比較手段による
比較の結果、上記プログラムの要素に対して上記文書デ
ータの要素が不足していないと判断されたときに、両要
素間で一致が検出された要素を合成してプログラムドキ
ュメントを生成する合成手段とを設けたものである。

【００１３】また、本発明の他の特徴とするところは、
上記比較手段による比較の結果、上記プログラムの要素
に対して上記文書データの要素が不足していると判断さ
れたときは、エラーを発生するようにしたものである。

【００１４】

【作用】本発明は上記技術手段より成るので、入力され
たプログラムの解析結果に基づいて、プログラムの各要
素についての内容がテンプレート形式でユーザにより記
述されていくことによって文書データが生成され、この
文書データが対応するプログラムに合成されてドキュメ
ントが作成されることとなり、上記プログラムとの間で
その内容にズレがなく、しかも、プログラムの各要素毎
にその内容を記述した詳細なドキュメントが常に作成さ
れる。

【００１５】さらに、上記プログラムの要素と文書デー
タの要素との合成に際して、両要素が比較され、プログ
ラムの要素に対して文書データの要素が不足していない
と判断されたときに、一致が検出された要素同志が相互
に合成されてドキュメントが作成されることとなるの
で、例えば、変数や関数が追加されたり、削除されたり
することによってプログラムの内容が変更された場合に
は、その変更後のプログラムに対応した詳細なドキュメ
ントが作成される。

【００１６】

【実施例】以下、本発明の一実施例を図面に基づいて説
明する。図１は、本実施例のプログラムドキュメント作
成装置の概略的な構成を示すブロック図である。図１に
おいて、プログラムドキュメント作成装置１は、文書デ
ータ生成装置２、文書データファイル記憶装置３、比較
合成装置４および構造化ドキュメントファイル記憶装置
５により構成されている。

【００１７】上記のようなプログラムドキュメント作成
装置１の構成において、文書データ生成装置２は、計算
機言語で記述されたプログラムをプログラムファイル記
憶装置６から読み出し、これを計算機言語の文法に従っ
て入力プログラムを解析することにより、後述するよう
な文書データのテンプレートを生成する。

【００１８】そして、文書データ生成装置２は、端末装
置７から入力される情報を上述のテンプレートに組み込
んで文書データを生成し、この生成した文書データを文
書データファイル記憶装置３に供給する。文書データフ
ァイル記憶装置３は、与えられた文書データを文書デー
タファイルとして格納する。

【００１９】また、比較合成装置４には、計算機言語で
記述されたプログラムがプログラムファイル記憶装置６
から入力されるとともに、上述のようにして生成された
文書データが文書データファイル記憶装置３から入力さ
れる。

【００２０】比較合成装置４は、入力されたプログラム
を計算機言語の文法に従って解析するとともに、文書デ
ータの文法に従って入力文書データを解析し、それぞれ
の要素を比較して合成することにより、後述するような
構造化ドキュメントを生成する。

【００２１】そして、生成した構造化ドキュメントを構
造化ドキュメントファイルとして構造化ドキュメントフ
ァイル記憶装置５に格納するとともに、プリンタや文書
清書システムなどの印刷装置８に出力する。

【００２２】次に、上述したプログラムドキュメント作
成装置１における文書データ生成装置２および比較合成
装置４の詳細な構成とその動作とについて、図２〜図１
１を参照しながら詳しく説明する。なお、図２は、文書
データ生成装置２の構成を示す図であり、図３は、比較
合成装置４の構成を示す図である。以下では、Ｃ++言語
の文字列に関するクラスStringについての構造化ドキュ
メントを作成する場合を例にとって説明する。

【００２３】まず、図２に示す文書データ生成装置２に
おいて、入力部１１は、プログラムファイル記憶装置６
に格納されているプログラムのうち、例えば、図４に示
すようなプログラムを取り込む。そして、入力部１１
は、プログラムファイル記憶装置６から取り込んだプロ
グラムをプログラム解析部１２に供給する。

【００２４】プログラム解析部１２は、入力されたプロ
グラムをＣ++言語の文法規則に従って解析する。すなわ
ち、プログラム解析部１２は、図４のようなプログラム
を複数の要素に分解し、それぞれの要素に名前を付ける
ことによって、図５に示すようなプログラムの解析結果
を得る。そして、プログラム解析部１２は、このように
して得られる解析の結果を、テンプレート生成部１３に
供給する。

【００２５】なお、図５において、各行のデータは、プ
ログラム解析部１２が分解したプログラムの要素をそれ
ぞれ示している。また、各行のclass String,ptr,getpt
r(),length()の文字は、それぞれプログラムの要素に付
けた名前を示している。

【００２６】次いで、テンプレート生成部１３は、プロ
グラム解析部１２による解析の結果に基づいて、図６に
示すような文書データのテンプレートを生成する。この
文書データのテンプレートは、プログラム解析部１２が
分解した上述のような各プログラムの要素毎に、各要素
に応じた必須項目を列挙したものである。

【００２７】すなわち、図６において、“class Strin
g”の要素の必須項目は、%status,%classlevel,%descri
ption,%history で示される４つの項目から成ってい
る。ここで、%status で示される項目は、例えば、実験
中、デバッグ中、あるいは公開済などのように、そのク
ラスの設計開発状況を示す項目である。

【００２８】また、%classlevel で示される項目は、例
えば、共通で使用可能、通信関連で使用可能、あるいは
ＧＵＩ関連で使用可能などのように、そのクラスのカテ
ゴリを示す項目である。さらに、%descriptionで示され
る項目は、そのクラスの機能説明を示す項目であり、%h
istoryで示される項目は、そのクラスの作成履歴を示す
項目である。

【００２９】一方、“ptr ”の要素の必須項目は、%des
cription,%noteで示される２つの項目から成っている。
ここで、%note で示される項目は、その要素を使用する
に当たっての注意事項を示す項目である。

【００３０】また、“getptr()”の要素および“length
()”の要素の必須項目は、それぞれ%description,%retu
rn,%noteで示される３つの項目から成っている。ここ
で、%return で示される項目は、関数の返り値を示す項
目である。上述した“ptr ”の要素は変数型の要素であ
るため、%return の項目は不要であるが、“getptr()”
の要素と“length()”の要素とは関数型の要素であるた
め、%return の項目が必要である。

【００３１】なお、テンプレート生成部１３は、プログ
ラムファイル記憶装置６から入力されたプログラムにつ
いて既に作成済みの文書データが文書データファイル記
憶装置３に格納されていることが入力部１１により確認
された場合は、その文書データを参照してテンプレート
を生成するようにする。

【００３２】そして、テンプレート生成部１３は、以上
のようにして生成した文書データのテンプレートを端末
装置７の表示部に表示し、ユーザによってこのテンプレ
ートの編集作業が行われるのを待つ。

【００３３】その後、ユーザが端末装置７のキーボード
などを操作して、表示部におけるテンプレートの表示項
目に沿ってその内容を記述していくと、文書データ生成
部１４は、文書データのテンプレート中に各項目の記述
内容を組み込んで、例えば、図７のような文書データを
生成する。

【００３４】そして、文書データ生成部１４は、このよ
うにして生成した文書データを出力部１５を介して文書
データファイル記憶装置３に供給する。文書データファ
イル記憶装置３は、与えられた文書データを文書データ
ファイルとして格納する。

【００３５】次に、図３に示す比較合成装置４におい
て、入力部２２は、上述のようにして生成した文書デー
タを文書データファイル記憶装置３から取り込み、この
文書データを文書データ解析部２４に供給する。また、
入力部２１は、図４に示したプログラムをプログラムフ
ァイル記憶装置６から取り込み、このプログラムをプロ
グラム解析部２３に供給する。

【００３６】プログラム解析部２３は、入力されたプロ
グラムをＣ++言語の文法規則に従って解析する。この場
合、プログラム解析部２３に入力されるプログラムは、
図２のプログラム解析部１２に入力されるプログラムと
同じであり、その解析結果も、図５に示したものと同じ
になる。そして、プログラム解析部２３は、このプログ
ラムの解析の結果得られる図５のようなデータを比較部
２５に供給する。

【００３７】一方、文書データ解析部２４は、入力され
た文書データをその文法に従って解析する。そして、文
書データ解析部２４は、この文書データの解析の結果得
られる図８のようなデータを比較部２５に供給する。

【００３８】なお、図８において、class String,ptr,g
etptr(),length()の各データは、それぞれ文書データの
要素を示している。また、class String,ptr,getptr(),
length()の文字は、それぞれ文書データの要素の名前を
示している。

【００３９】次いで、比較部２５は、上述のようにして
プログラム解析部２３が解析したプログラムの要素と、
文書データ解析部２４が解析した文書データの要素とを
比較し、それぞれに同じ名前の要素が存在するかどうか
を確認する。そして、比較部２５は、その比較の結果に
応じて、入力したプログラムおよび文書データの中か
ら、所定の要素を合成部２６に供給する。

【００４０】すなわち、図５および図８に示した上述の
例のように、プログラムの要素と文書データの要素との
間ですべての要素の名前が一致している場合は、比較部
２５は、そのすべての要素を合成部２６に供給する。

【００４１】一方、文書データの要素に対してプログラ
ムの要素が不足しているような場合は、比較部２５は、
両者の名前が一致する要素のみを合成部２６に供給す
る。例えば、図９に示すように、文書データの要素とし
て存在する“length()”の要素がプログラムの要素とし
ては存在しない場合には、比較部２５は、文書データの
“length()”の要素は合成部２６に供給せず、両者の名
前が一致する“class String,ptr,getptr() ”の要素の
みを合成部２６に供給する。

【００４２】さらに、これとは逆に、プログラムの要素
に対して文書データの要素が不足している場合は、プロ
グラム中には存在するにもかかわらず、文書データには
存在しない要素があることになるので、プログラムの正
しいドキュメントを得ることができない。

【００４３】したがって、この場合には、比較部２５
は、例えば、端末装置７の表示部にエラー表示をして、
文書データの要素が不足していることをユーザに知らせ
る。そして、このようなエラーの発生を確認して、ユー
ザが文書データを生成し直すことにより、正しいドキュ
メントを常に得ることができるようにする。

【００４４】次いで、合成部２６は、比較部２５から入
力されたプログラムの要素と文書データの要素とを相対
応させて合成する。この合成の結果を、図１０に示す。
さらに、合成部２６は、端末装置７から与えられる所定
のパラメータに基づいて、図１０に示した合成の結果を
調整し、この調整の結果得られるデータを出力部２７に
供給する。

【００４５】すなわち、合成部２６は、例えば、プログ
ラム解析部２３によるプログラムの解析の結果得られる
データ中にprivate 部を含んでいる要素は出力部２７に
供給しないように調整することができる。図１０の例で
は、合成部２６は、private部を含んでいる“ptr ”以
外の要素を出力部２７に供給する。

【００４６】また、合成部２６は、例えば、文書データ
解析部２４による文書データの解析の結果得られるデー
タのうち、noteに関する部分のデータは出力部２７に供
給しないように調整することができる。図１０の例で
は、合成部２６は、“ptr ”の要素中のnoteの行を除い
た部分のデータを出力部２７に供給する。

【００４７】次いで、出力部２７は、合成部２６から与
えられるデータを構造化ドキュメントファイル記憶装置
５に供給する。そして、構造化ドキュメントファイル記
憶装置５は、与えられたデータを構造化ドキュメントフ
ァイルとして格納する。このようにして、プログラムの
内容をその属性名、簡単な機能説明、注意事項などを各
要素毎に詳細に記述した構造化ドキュメントを得る。

【００４８】また、出力部２７は、上述の合成部２６か
ら与えられるデータを、印刷装置８が理解できるフォー
マットに変換して印刷装置８に出力する。そして、印刷
装置８は、与えられたデータに基づいて、図１１に示す
ようなドキュメントの印刷を実行する。

【００４９】以上のように、本実施例のプログラムドキ
ュメント作成装置では、入力したプログラムをその文法
規則に従って解析し、その解析の結果に基づいて文書デ
ータのテンプレートを生成するとともに、このテンプレ
ートを端末装置の表示部に表示する。次いで、ユーザが
この表示内容を参照してテンプレート中の必須項目の内
容を記述していくことによって、文書データを生成する
ようにしている。

【００５０】そして、この文書データの生成の際に、必
須項目の記述漏れなどがあった場合には、エラーを発生
してユーザにその旨を知らせる。そして、記述漏れのあ
った項目の内容をユーザが追加して記述することによっ
て文書データを完成させるようにしているので、誰が作
成しても必須項目の欠落がない一定の品質以上のドキュ
メントを作成することができる。

【００５１】また、本実施例のプログラムドキュメント
作成装置では、上述のように、入力したプログラムの解
析結果に基づいて生成したテンプレートの必須項目をユ
ーザが埋めていくことによって文書データを生成するよ
うにしている。このため、通常は、プログラムと文書デ
ータとの間では、その内容にズレはない。

【００５２】これに対して、あるプログラムについて既
に生成済みの文書データを利用してドキュメントを作成
する場合には、プログラムに変数や関数を新たに加えた
り、逆に、プログラムから変数や関数を削除したりする
ことによって、プログラムの内容と文書データの内容と
にズレが生じることがある。

【００５３】そこで、本実施例のプログラムドキュメン
ト作成装置では、プログラムに変数や関数を新たに加え
ることによって、プログラムの要素に対して文書データ
の要素が不足するような場合には、エラーを発生してユ
ーザにその旨を知らせ、文書データを生成し直すように
している。

【００５４】一方、プログラムから変数や関数を削除す
ることによって、文書データの要素に対してプログラム
の要素が不足するような場合には、文書データにのみ存
在する要素は無視してドキュメントを作成するようにし
ている。したがって、プログラムの変更を反映したドキ
ュメントを常に作成することができる。

【００５５】さらに、本実施例のプログラムドキュメン
ト作成装置では、所定のパラメータを用いて構造化ドキ
ュメントの内容を調整できるようにしているので、プロ
グラムの開発者や利用者などの対象のレベルに応じた複
数のドキュメントを１つのプログラムから作成すること
ができる。

【００５６】

【発明の効果】以上説明したように本発明によれば、入
力したプログラムの解析結果に基づいて、プログラムの
各要素についての内容をテンプレート形式でユーザが記
述していくことによって文書データが生成されるととも
に、この文書データの要素と上記プログラムの要素とが
比較され、プログラムの要素に対して文書データの要素
が不足していないと判断されたときに、一致が検出され
た要素同志が相互に合成されてドキュメントが作成され
るので、プログラムの各要素毎にその内容を記述した詳
細なドキュメントを常に作成することができ、さらに、
対象となるプログラムの内容を変更した場合にも、その
プログラムの変更を反映した詳細なドキュメントを作成
することができる。したがって、誰が作成しても、一定
の品質以上のドキュメントを常に作成することができ、
このため、例えば、プログラム部品の検索や、プログラ
ムソースの再利用を容易にして、プログラムの編集を効
率的に行うようにすることができる。

【図面の簡単な説明】

【図１】本発明のプログラムドキュメント作成装置の概
略的な構成を示すブロック図である。

【図２】文書データ生成装置の構成を示すブロック図で
ある。

【図３】比較合成装置の構成を示すブロック図である。

【図４】プログラムファイル記憶装置から入力するプロ
グラムの例を示す図である。

【図５】プログラムの解析結果の例を示す図である。

【図６】文書データのテンプレートの例を示す図であ
る。

【図７】文書データの例を示す図である。

【図８】文書データの解析結果の例を示す図である。

【図９】プログラムの解析結果と文書データの解析結果
との例を示す図である。

【図１０】プログラムの要素と文書データの要素との合
成結果の例を示す図である。

【図１１】構造化ドキュメントの例を示す図である。

【図１２】従来のプログラム編集装置の処理を概略的に
示す動作説明図である。

【符号の説明】 １ プログラムドキュメント作成装置 ２ 文書データ生成装置 ３ 文書データファイル記憶装置 ４ 比較合成装置 ５ 構造化ドキュメントファイル記憶装置 ６ プログラムファイル記憶装置 ７ 端末装置 ８ 印刷装置 １１ 入力部 １２、２３ プログラム解析部 １３ テンプレート生成部 １４ 文書データ生成部 １５ 出力部 ２１、２２ 入力部 ２４ 文書データ解析部 ２５ 比較部 ２６ 合成部 ２７ 出力部

Claims (2)

【特許請求の範囲】
1. 【請求項１】 入力したプログラムをそのプログラミン
   グ言語の文法に従って構文解析し、上記プログラムを種
   々の要素に分解するプログラム解析手段と、 上記プログラム解析手段により分解されたプログラムの
   要素毎に、テンプレート形式で文書を記述することによ
   って、上記プログラムの内容を表す文書データを生成す
   る文書データ生成手段と、 上記文書データをその文法規則に従って解析し、上記文
   書データを種々の要素に分解する文書データ解析手段
   と、 上記プログラム解析手段により分解されたプログラムの
   要素と、上記文書データ解析手段により分解された文書
   データの要素とを比較し、上記プログラムの要素に対応
   する文書データの要素が存在するか否かを確認する比較
   手段と、 上記比較手段による比較の結果、上記プログラムの要素
   に対して上記文書データの要素が不足していないと判断
   されたときに、両要素間で一致が検出された要素を合成
   してプログラムドキュメントを生成する合成手段とを設
   けたことを特徴とするプログラムドキュメント作成装
   置。
2. 【請求項２】 請求項１記載のプログラムドキュメント
   作成装置において、上記比較手段による比較の結果、上
   記プログラムの要素に対して上記文書データの要素が不
   足していると判断されたときは、エラーを発生するよう
   にしたことを特徴とするプログラムドキュメント作成装
   置。