14

私は長い間 Perl プログラマーですが、POD のドキュメントには常に問題があります。

コードで POD コメントを使用すると、コードが読みにくくなります。ファイルの最後に POD コメントを使用すると、ドキュメントがコードと同期されない危険性があります。

Java に似たドキュメント スタイルが恋しいです。

/**
 * @description
 * ...
 */

私は、より簡単で直感的なドキュメンテーション スタイルを探しています。そのようなことはありますか？

4

6 に答える 6

9

クイック検索で、 Doxygenスタイルのコメント (Javadoc に非常に近い) を使用して Perl コードを文書化できるようにすることを目的としたDoxygen Filterが見つかりました。

于 2011-01-18T09:54:28.213 に答える
8

POD は、Perl ドキュメントを公開するための標準として認められています。

維持するのもかなり面倒だと思います。私は最近、Pod::Weaverを使用してドキュメントを維持し、リリース時に Pod に組み込む実験を行いました。POD のフィルタリングとビルドの方法が非常に柔軟であり、(POD またはその他の方法で) もう少しドキュメントを使用できるという点で、少し注意が必要です。しかし、有望なようです。それ以上の判断を下すにはまだ時期尚早ですが、有望に思えます。

お役に立てれば

于 2011-01-18T11:57:32.700 に答える
7

Why do you think the code is hard to read with Pod? Is the code hard to read with other code around it? Perhaps you're putting too much into a particular part of the code, instead of writing small methods, etc. Are you sure it's not your code that's hard to read?

You don't have to put all of your documentation at the end of the code. Pod is perfectly fine inline with code, allowing you to put the documentation for a subroutine or method right next to the subroutine or method.

Is there some other problem you have with Pod?

于 2011-01-18T13:09:43.273 に答える
3

私がPODで問題を抱えたのは、正しく強調表示されないテキストエディタを使用しているときだけです。

Javaのすべてと同じように、これは過度に冗長に見えます。

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute  

{@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 *  

@param  url  an absolute URL giving the base location of the image
 *  

@param  name the location of the image, relative to the url argument
 *  

@return      the image at the specified URL
 *  

@see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }

同等のPerlと比較した場合。

=item getImage( url, name )

This method always returns immediately, whether or not the 
image exists. When this applet attempts to draw the image on
the screen, the data will be loaded. The graphics primitives 
that draw the image will incrementally paint on the screen. 

url must be an absolute URL giving the base location of the image

name is the location of the image, relative to the url argument

=cut

sub getImage{
  my ($url,$name) = @_;

  ...
}
于 2012-02-20T15:44:33.000 に答える
1

Rinciをご覧になることをお勧めします。これを使用するアプリケーションの例: File::RsyBak、Git::Bunch、App::OrgUtils。

モジュールを文書化する方法は次のとおりです。モジュールで %SPEC を宣言し、ドキュメントをその中に入れます。各関数は独自のキーを取得します。定義済みのフィールドがあります。ローカリゼーションがサポートされています。書式設定は Markdown で行います。例：

$SPEC{':package'} = {
    summary => 'Module to do foo',
    "summary.alt.lang.id_ID" => "Modul untuk melakukan foo",
    description => <<EOT,
Blah...
...
EOT
    links => [...],
};
$SPEC{func1} = {
    summary => '...',
    description => '...',
    args => {
        arg1 => {
            schema => ...,
            summary => ....,
            description => ...,
        },
    },
    examples => [...],
    links => [...],
    ...
};

Java または Perl 5 スタイルのドキュメントを「コメント」に入れる代わりに、プログラムで直接利用できるデータ構造を使用します。(Perl 6 もこの方向に進んでいることに注意してください。) これは、Python docstring が狂った (または構造化された) ものと考えてください。

メタデータ (仕様) から POD、テキスト、HTML を生成するツールがあります。ドキュメントとは別に、メタデータは引数の検証、コマンドライン インターフェイスなどにも役立ちます。

開示：私は開発者です。

于 2012-03-16T00:48:40.903 に答える