タグ付けされた質問 「documentation-generation」

象徴的な「Given-When-Then」シナリオ構文を使用した動作駆動型開発は、ソフトウェア機能評価の境界オブジェクトとして使用できる可能性があるため、最近非常に誇張されています。 Gherkin、またはどちらの機能定義スクリプトでも、ビジネスで読み取り可能な DSLであり、すでにそのような価値を提供していることは間違いありません。 ただし、プログラマではない人が書き込み可能であることに同意しません（Martin Fowlerも同様です）。 プログラマ以外の人が作成し、開発者がインスツルメントしたシナリオのアカウントを持っている人はいますか？ 書き込み可能性の欠如についてコンセンサスがある場合、シナリオを開始してそれらをインストルメント化する代わりに、実際のテストからビジネスで読み取り可能なシナリオを生成するツールに問題がありますか？ 更新：「シナリオジェネレータ」ツールに関しては、もちろんビジネス言語を魔法のように推測することはありません;）しかし、現在、正規表現マッチャーを使用して（抽象化次元で）トップダウンアプローチでテストを作成するように、ボトムアップアプローチでシナリオを作成する文字列ビルダー。 「アイデアのみを提供する」例： Given I am on page ${test.currentPage.name} And I click on element ${test.currentAction.element} …

24 documentation  bdd  documentation-generation  business-rules 

閉じた。この質問はより集中する必要があります。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集するだけで1つの問題に焦点を当てるように質問を更新します。 去年閉鎖されました。 数か月後にコードの読み取りと閲覧を最小限に抑えるようにコードを文書化したい。 さまざまな種類のドキュメントがあることを知っています（ソースコードと外部、シーケンス図など）。 コードを効率的に文書化する方法を知りたいので、数か月後にコードを確認したいとき、コードの読み取りとコードフローの理解に費やす時間が少なくなります。

22 documentation  code-reviews  documentation-generation  help-documentation 

だから私たちはそのようなインターフェイスを持っています /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos /// </summary> void Create(Foo foo); /// <summary> /// Does Bar stuff /// </summary> void Bar(); } 最近、私たちは、上記のようなXML文書がたくさんあることを生成し、確認することを含む文書の話をしました。しかし、これはドキュメントの多くの重複を引き起こしました。実装例： /// <summary> /// A Foo Creator which is fast /// </summary> …

20 c#  documentation  xml  documentation-generation 

私は現在、2つのシステムを使用してコードドキュメントを記述しています（C ++を使用しています）。 Doxygen形式を使用して、メソッドとクラスメンバーに関するドキュメントがコードの横に追加されます。サーバーでは、Doxygenがソースで実行されるため、Webブラウザーで出力を確認できます。 概要ページ（クラスのセット、アプリケーションの構造、サンプルコードなど）がWikiに追加されます。 メンバーやクラスに関するドキュメントはコードに非常に近いため、このアプローチは簡単だと個人的に思いますが、概要ページはWikiで編集するのが非常に簡単です（また、画像、表などを追加するのも簡単です）。Webブラウザを使用すると、両方のドキュメントを表示できます。 私の同僚は、すべてをDoxygenに入れることを提案しています。これは、MicrosoftのHTML WorkShopまたはQt Assistantを使用して、すべてを含む1つの大きなヘルプファイルを作成できるためです。私の懸念は、特に表、画像などを追加する場合、Doxygenスタイルのドキュメントの編集がはるかに難しいことです（Wikiと比較して）（または、生成する必要のないDoxygenの「プレビュー」ツールがありますか？結果を見る前のコード？） 大きなオープンソース（またはクローズドソース）プロジェクトは、コードド​​キュメントを書くために何を使用しますか？彼らはこれをDoxygenスタイルとWikiに分けていますか？または、別のシステムを使用していますか？ ドキュメントを公開する最も適切な方法は何ですか？Webサーバー/ブラウザ経由、または大きな（数MBの）ヘルプファイル経由？ コードドキュメントを作成するとき、どのアプローチを取りますか？

13 documentation  documentation-generation  wiki 

メソッドまたはAPIがコードベースにあるが、実装が完全ではないか、変更される可能性が高いため、使用すべきではないという意味で、「非推奨」と似ているが異なる用語はありますか？（ええ、私は知っています、これらの方法は公開すべきではありません、やだやだやだ。自分の状況を作り出したのではなく、それを最大限に活用しようとしています。） 人々は何を提案しますか？実験的、不完全、他の何か？ まだ流動的なこのAPIのjavadocドキュメントを構築している場合、@ deprecatedタグを使用する必要がありますか、それともより良い規則がありますか？私にとって@deprecatedは、このAPIが古く、新しい優先メカニズムが利用可能であることを意味します。私の状況では、代替手段はありませんが、APIの一部のメソッドは終了していないため、使用しないでください。この時点では、それらを非公開にすることはできませんが、ドキュメントに明確な警告を記載したいと思います。

12 documentation  terminology  api  documentation-generation  javadocs 

閉じた。この質問はより集中する必要があります。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集するだけで1つの問題に焦点を当てるように質問を更新します。 4年前に閉鎖されました。 基本的にPHPで開発されたWebアプリケーションを完成させましたが、これはもう1つの通常のWebアプリケーションです。通常、最終製品リリースを配信するときは、コードド​​キュメントとアーキテクチャ情報をクライアントに引き渡すだけです。ただし、この特定のプロジェクトでは、クライアントはプロジェクトに関する完全な入出力データを保持することを強く求めています。 だから私はただ疑問に思っています...コードとアーキテクチャのドキュメントとは別にクライアントに提供できる必須の技術的および非技術的ドキュメントは何ですか？ （また、プロジェクトに関するさまざまな統計情報やデータについてクライアントにヒットして、関連する作業量と製品が実際にどれだけクールであるかを実際に知ることもできます。）

11 project-management  documentation  documentation-generation  projects-and-solutions 

のコードをドキュメント化しましたが、コードdoxygenが提供するデフォルトのHTMLは必要ありません。（GNOMEのように）カスタムCSS、ヘッダー、フッターなどを提供することでカスタマイズできること、そして一般的なPHPコードをファイルに追加してとして保存するように指示する方法を.php知っていますが、それは本当に望んでいることではありません。 私が欲しいのはMSDNのような出力です。私はそれを本当に説明することはできません。私の質問は、テンプレートのようなものでdoxygenを使用してこれは可能ですか、それともXMLを出力して別のプログラムで解析する必要がありますか（私は書いてもかまわないでしょう）。

10 documentation  templates  documentation-generation 

私はC＃でいくつかの定量ライブラリを開発しました。XMLDocコメントに関連する古典的な情報（メソッドシグネチャの基本情報を含む）だけでなく、メソッド内で使用されている数式も理解することが重要です。 したがって、コードに拡張ドキュメントを含めることができるようにしたいと考えています。これには、たとえば、ラテックスの数式、グラフなどを含めることができます。 そのような情報をAPIドキュメントに含める必要があると思いますか？ または、例として開発ブログに含める必要がありますか？ この種の目的で通常使用される一般的なツールはありますか？

8 documentation  documentation-generation