ホームページ バックエンド開発 PHPチュートリアル PHP クラスを文書化する方法 (1)_PHP チュートリアル

PHP クラスを文書化する方法 (1)_PHP チュートリアル

Jul 21, 2016 pm 02:56 PM
l php 1つ 著者 どうやって 書類 親切 翻訳する

PHP クラスを文書化する方法 (1)


著者: stefano Locati 翻訳: limodou


You have read about: オブジェクト指向プログラミングは大規模な Web プロジェクトの管理に役立ちます、そしてあなたは PHP を使い始めましたオブジェクト指向プログラミングをやったことがありますか? Web サイトで使用するいくつかのクラスを作成し、組織化された人であれば、それらについてのドキュメントを作成しているはずです。ただし、私のようなカジュアルな人の場合は、他のドキュメントを必要とせずに、クラスのソース コードにコメントを追加するだけです。ドキュメントがなければ、メソッドの名前とその使用方法 (パラメーターと意味) を覚えるのは困難です。この状況に対する最も一般的な解決策は、ソース コード ファイルを開いて、数百または数千のステートメントを検索することです。


Javadoc のようなドキュメント

良い方法があるはずです。Java 言語を使用したことがあるなら、Javadoc ドキュメント システムを知っているでしょう。このツールを使用すると、ソース コード ファイルのコメントにタグを挿入できます。これを Javadoc ツールで分析して、クラスを文書化するための一連の HTML ページを生成できます。こうすることで、プログラミング中にブラウザを開いて、クラスのリストと説明付きのクラス メソッドのリストを取得できます。 Webアプリケーションを開発する際の参考となり、作業効率の向上や開発のスピードアップにつながります。


私の意見は、参照ドキュメントをソース コード内で参照として維持する方が、別のドキュメントを維持するよりも簡単で、より実用的である、というのがこの方法の方が更新し続けるのが容易だからです。そうしないと、怠けてドキュメントの更新を無期限に延期してしまいがちです (期限を設けるとしたら 10,000 年だと思います)。このようなツールを使用する代わりに、変更するソース コードの近くのタグを更新し、ツールを再度実行して更新された HTML ページを生成するだけです。


いくつかの php ドキュメント ツールのプレビュー

上記を理解した後、利用可能なものを探したところ、次の興味深いツールを見つけました:


phpSearchdoc は酵素プロジェクトの一部です。酵素は大規模なプロジェクトであるため、文書化する必要があります。そこの開発者は独自のドキュメント システムを作成し、それをスタンドアロン パッケージとしてリリースするのに十分寛大です。作成されたドキュメントはまずデータベースに書き込まれ、その後、動的 Web サイトなどの PHP スクリプトで表示できます。


分析用のロジックを既存の情報から分離するというアイデアは非常に優れていますが、phpSearchdoc (バージョン 1.01) には実際のアナライザーがありませんが、ソース ファイルからキーワードを検索し、コメントも検索します。実際、私のコメントの 1 つに「関数」という単語が含まれていたことが起こり、パーサーは愚かにもこの単語に続く単語が関数の名前であると考えました。さらに残念なことに、たまたま同じ行に一重引用符 (') を入れてしまい、データをデータベースに書き込もうとしたところ、mysql からエラーが発生しました ( mysql では文字列を区切るために一重引用符が使用されているため、エラーが発生しました)。


そして、まだアルファテスト版なので、インストールして実行するのはかなり難しいです。結局のところ、これはドキュメント システムというよりも相互参照ジェネレーターであり、私が知っているように、関数やメソッドに独自のコメントを追加することはできません。


phpxrefは、その名前が示すように、実際のドキュメントシステムというよりも相互参照生成プロセスに似ているようです。さらに、オブジェクト指向プログラミングよりも通常の手続き型プログラミングに適しています。


phpautodocの目標は、JavadocがJavaで使用されるのと同じように、PHPで使用されることです。私のドキュメントのニーズにとって完璧なソリューションのように思えました。ジェネレーターは PHP で書かれているため、テストするには PHP の CGI バージョンをコンパイルする必要がありました (通常はモジュール バージョンを使用します)。これらのコマンドを使用すると、静的実行可能ファイルを Linux システムに簡単にコンパイルしてインストールできます:


rm config.chche

make clean

./configure

make

cp php /usr/local/ bin


独自の PHP ソース コードでテストしてみたところ、部分的にしか機能しなかったことがわかりました。クラスのドキュメント (きちんとした形式で) のみ生成できましたが、概要は生成できませんでした。これが私のマシンでたまたま起こったのかどうかはわかりませんが、概要を生成しようとするとコアダンプで停止しました(PHP 4.0 pl2、RedHat 6.2環境)。 PHP 実行可能バージョンが machine/usr/local/bin にインストールされている場合、それを呼び出す構文は次のとおりです (結果を取得するには、php ファイルと出力ディレクトリのフル パスを指定する必要があります)


./ phpautodoc -o


phpdoc は Web サイト上で保守するために使用される php ファイルであり、分散開発に非常に適しています。ドキュメントはデータベースから生成されます。インストール後、Web インターフェイスを使用してクラスを追加し、ドキュメントを作成できます。これは確かに興味深いですが、ドキュメントとソース コードを分離する低レベルのメンテナンス方法であり、私にとってはあまり便利ではありません。


ユニバーサルツール

Pear プロジェクトが標準ソリューションを思いつくまで、これらすべてのツールを試してもあまり成功せずに挫折した後、Apple サイトの Open Source Projects で PHP とはまったく関係のない実用的なツールを見つけました。プロジェクトの名前は HeaderDoc です。サイトにあるように、「HeaderDoc は、C または C++ ヘッダー ファイルのコメントから HTML リファレンス ドキュメントを生成するツールです。移植性を高めるために Perl で書かれています。JavaDoc と同様に、開発者はインターフェイスを簡単に文書化し、インターフェイス情報を出力できます。 HTML "


はい、お読みのとおり、HeaderDoc は C と C++ のみをサポートします。他の言語ではありませんが、JavaDoc とは異なり、主にコメントに記述されたマークアップに依存しているため、いくつかの小さな変更を加えるだけで PHP とうまく連携できます (これについては後ほど説明します)。これらのタグは JavaDoc に非常に似ています。HeaderDoc タグの例としては、@class、@function、@var などがあります。


クラスの文書化

それでは、詳細を見ていきましょう。まず、クラスがどのように文書化されるかを見てみましょう。


---------------------------------------------- --- ----------------------------------

/*! @class BagItem

@abstract Anショッピング バッグ内のアイテム - それは数量を持つ shopitem です

@Discussion BagItem オブジェクトは、ShopItem も Product も事前に

インスタンス化することなく構築できます

*/

----------- ---------------------------------------------------- --------------------


クラスを文書化します。左フレームでクラスメソッドを選択できます。


最初に注意すべきことは、コメントを開くために使用されるスタイルは JavaDoc コメント /** (1 つのスラッシュと 2 つのアスタリスク) とまったく同じではなく、/* (1 つのスラッシュ、1 つのアスタリスク、および感嘆符) に置き換えられていることです。 )。タグの使用法も異なりますが、同様に機能します。たとえば、最初のタグは @class タグで、クラスを文書化するために使用されます。このタグの後にクラスの名前が続きます。次のタグは @abstract タグです。これはクラスの意味を数語で説明するオプションのタグであり、@Discussion タグはさらなる議論に使用されるもう 1 つのオプションのタグです。もちろん、すべてを @Discussion タグで記述するか、@abstract を使用して処理するかを決定するのはあなた次第ですが、一般に、使用するタグが正確であればあるほど、より良い結果が得られることに留意してください。


原著者: limodou

出典: PHPX


http://www.bkjia.com/PHPjc/364121.html

tru​​ehttp://www.bkjia.com/PHPjc/364121.html技術記事 PHP クラスを文書化する方法 (1) 著者: stefano Locati 翻訳: limodou 次について読みました: オブジェクト指向プログラミングは大規模な Web プロジェクトの管理に役立ちます。そして、あなたは始めました...
このウェブサイトの声明
この記事の内容はネチズンが自主的に寄稿したものであり、著作権は原著者に帰属します。このサイトは、それに相当する法的責任を負いません。盗作または侵害の疑いのあるコンテンツを見つけた場合は、admin@php.cn までご連絡ください。

ホットAIツール

Undresser.AI Undress

Undresser.AI Undress

リアルなヌード写真を作成する AI 搭載アプリ

AI Clothes Remover

AI Clothes Remover

写真から衣服を削除するオンライン AI ツール。

Undress AI Tool

Undress AI Tool

脱衣画像を無料で

Clothoff.io

Clothoff.io

AI衣類リムーバー

AI Hentai Generator

AI Hentai Generator

AIヘンタイを無料で生成します。

ホットツール

メモ帳++7.3.1

メモ帳++7.3.1

使いやすく無料のコードエディター

SublimeText3 中国語版

SublimeText3 中国語版

中国語版、とても使いやすい

ゼンドスタジオ 13.0.1

ゼンドスタジオ 13.0.1

強力な PHP 統合開発環境

ドリームウィーバー CS6

ドリームウィーバー CS6

ビジュアル Web 開発ツール

SublimeText3 Mac版

SublimeText3 Mac版

神レベルのコード編集ソフト(SublimeText3)

Ubuntu および Debian 用の PHP 8.4 インストールおよびアップグレード ガイド Ubuntu および Debian 用の PHP 8.4 インストールおよびアップグレード ガイド Dec 24, 2024 pm 04:42 PM

PHP 8.4 では、いくつかの新機能、セキュリティの改善、パフォーマンスの改善が行われ、かなりの量の機能の非推奨と削除が行われています。 このガイドでは、Ubuntu、Debian、またはその派生版に PHP 8.4 をインストールする方法、または PHP 8.4 にアップグレードする方法について説明します。

PHP 開発用に Visual Studio Code (VS Code) をセットアップする方法 PHP 開発用に Visual Studio Code (VS Code) をセットアップする方法 Dec 20, 2024 am 11:31 AM

Visual Studio Code (VS Code とも呼ばれる) は、すべての主要なオペレーティング システムで利用できる無料のソース コード エディター (統合開発環境 (IDE)) です。 多くのプログラミング言語の拡張機能の大規模なコレクションを備えた VS Code は、

今まで知らなかったことを後悔している 7 つの PHP 関数 今まで知らなかったことを後悔している 7 つの PHP 関数 Nov 13, 2024 am 09:42 AM

あなたが経験豊富な PHP 開発者であれば、すでにそこにいて、すでにそれを行っていると感じているかもしれません。あなたは、運用を達成するために、かなりの数のアプリケーションを開発し、数百万行のコードをデバッグし、大量のスクリプトを微調整してきました。

PHPでHTML/XMLを解析および処理するにはどうすればよいですか? PHPでHTML/XMLを解析および処理するにはどうすればよいですか? Feb 07, 2025 am 11:57 AM

このチュートリアルでは、PHPを使用してXMLドキュメントを効率的に処理する方法を示しています。 XML(拡張可能なマークアップ言語)は、人間の読みやすさとマシン解析の両方に合わせて設計された多用途のテキストベースのマークアップ言語です。一般的にデータストレージに使用されます

JSON Web Tokens(JWT)とPHP APIでのユースケースを説明してください。 JSON Web Tokens(JWT)とPHP APIでのユースケースを説明してください。 Apr 05, 2025 am 12:04 AM

JWTは、JSONに基づくオープン標準であり、主にアイデンティティ認証と情報交換のために、当事者間で情報を安全に送信するために使用されます。 1。JWTは、ヘッダー、ペイロード、署名の3つの部分で構成されています。 2。JWTの実用的な原則には、JWTの生成、JWTの検証、ペイロードの解析という3つのステップが含まれます。 3. PHPでの認証にJWTを使用する場合、JWTを生成および検証でき、ユーザーの役割と許可情報を高度な使用に含めることができます。 4.一般的なエラーには、署名検証障害、トークンの有効期限、およびペイロードが大きくなります。デバッグスキルには、デバッグツールの使用とロギングが含まれます。 5.パフォーマンスの最適化とベストプラクティスには、適切な署名アルゴリズムの使用、有効期間を合理的に設定することが含まれます。

母音を文字列にカウントするPHPプログラム 母音を文字列にカウントするPHPプログラム Feb 07, 2025 pm 12:12 PM

文字列は、文字、数字、シンボルを含む一連の文字です。このチュートリアルでは、さまざまな方法を使用してPHPの特定の文字列内の母音の数を計算する方法を学びます。英語の母音は、a、e、i、o、u、そしてそれらは大文字または小文字である可能性があります。 母音とは何ですか? 母音は、特定の発音を表すアルファベットのある文字です。大文字と小文字など、英語には5つの母音があります。 a、e、i、o、u 例1 入力:string = "tutorialspoint" 出力:6 説明する 文字列「TutorialSpoint」の母音は、u、o、i、a、o、iです。合計で6元があります

PHPでの後期静的結合を説明します(静的::)。 PHPでの後期静的結合を説明します(静的::)。 Apr 03, 2025 am 12:04 AM

静的結合(静的::) PHPで後期静的結合(LSB)を実装し、クラスを定義するのではなく、静的コンテキストで呼び出しクラスを参照できるようにします。 1)解析プロセスは実行時に実行されます。2)継承関係のコールクラスを検索します。3)パフォーマンスオーバーヘッドをもたらす可能性があります。

PHPマジックメソッド(__construct、__destruct、__call、__get、__setなど)とは何ですか? PHPマジックメソッド(__construct、__destruct、__call、__get、__setなど)とは何ですか? Apr 03, 2025 am 12:03 AM

PHPの魔法の方法は何ですか? PHPの魔法の方法には次のものが含まれます。1。\ _ \ _コンストラクト、オブジェクトの初期化に使用されます。 2。\ _ \ _リソースのクリーンアップに使用される破壊。 3。\ _ \ _呼び出し、存在しないメソッド呼び出しを処理します。 4。\ _ \ _ get、dynamic属性アクセスを実装します。 5。\ _ \ _セット、動的属性設定を実装します。これらの方法は、特定の状況で自動的に呼び出され、コードの柔軟性と効率を向上させます。

See all articles