ダメなマニュアルの特徴 - まめめも
めちゃくちゃ遅い反応ですが、「よく言ってくれた！」という話。 現状のRDocはユーザリファレンスに向いてないと思ってる。 RDoc書いただけで「リファレンスは完璧だお！」とか言ってるやつなんなの - Greenbear Diary (2009-06-04) 以下関係あるようなないような話。わが身は振り返らない方向で。 ダメなマニュアルの特徴 rdoc に限った話ではないですが、以下はダメなマニュアルに共通する特徴だと思います。 クラスやメソッドを ABC 順に並べている メソッドの説明が長い サンプルコードがない こういう文書は読み手を普通のプログラマだと思ってません。 なぜダメか ABC 順だと、どこから読めばいいかわからない。砂漠の真ん中で迷子になったような気分になります。早く使ってみたいのに使えない歯がゆさ。 説明が長いのは、メソッドの名前が適切でない可能性や、無駄に全機能を列挙しよ
Javadoc の書き方 - イトウ アスカ blog
みなさん、Javadoc 書いてますか？ Javadoc は「API ドキュメント」と言われることが多いように、主にライブラリ的なプログラムで書いてこそのものだと思っている方もいるかもしれません。しかしながら、仕様書を Word や Excel（笑）で別途作ると、プログラムと仕様書の同期がとれてないというはめに陥り易くなりますので、Javadoc はどんなときも活用したいというのが私の考え方です。 まず、overview.html を書け Javadoc コメントをいくらか書くような人でも、overview.html を書く人は意外と少ないのではないでしょうか。リファクタリングが何度となく行われるアジャイル開発の現場では、クラスの構成がよくかわりますので、いちいち詳しいコメントを書いていられないということはあるかもしれませんが、overview.html はそれほど何度も手をつけるようなも
How to Write Doc Comments for the Javadoc(TM) Tool
Javadoc Home Page This document describes the style guide, tag and image conventions we use in documentation comments for Java programs written at Java Software, Oracle. It does not rehash related material covered elsewhere: For reference material on Javadoc tags, see the Javadoc reference pages. For the required semantic content of documentation comments, see Requirements for Writing Java API Spe
Java Documentation in Windows Help format (WinHelp and HTMLHelp)
This Web site provides various Java documentation converted to Windows Help format. WinHelp and HtmlHelp systems provides a structured table of contents, a complete index, and a full-text search feature. Don't remember the parameters of StringBuffer.replace() ? Just type 'replace' in the index, and you get it in a snap. Alternatively, you can browse the table of contents tree to find the StringBuf
[Think IT] 第3回：「どのように検証するのか」をJavadocで実現する (1/3)
Javadocはソースコードとドキュメンテーションコメントからリファレンスドキュメントを作成するツールです。ソースコード中のクラス宣言やメソッド宣言と、それらの内容についての説明が書かれたドキュメンテーションコメントを、Javadocが解析してHTML形式のリファレンスドキュメントを作成します。 ソースコードを書く開発者は通常、クラスやメソッドを設計・開発しながら、設計について「なぜそうなっているのか」といった説明や利用の仕方をドキュメンテーションコメントとして残すことができます。つまり、Javadocで作成したリファレンスドキュメントをみれば、クラスやメソッドの設計や利用について、開発者の意図したところが理解できるのです。 しかし、通常のJavadocで作成されたリファレンスドキュメントだけだと、ソースコードをどういう意図で作ったのかはわかりますが、そのソースコードが正しいかということま
[Think IT] 第2回：「どんなシステムを作るのか」をJavadocで表現する (1/3)
Javadocの機能は、ソースコード中の「/**」と「*/」で囲まれたドキュメンテーションコメントから、リファレンスドキュメントを生成することでした。ソースコードとドキュメンテーションコメントが一体になっているため、開発者は設計を考えながらソースコードを書き、その設計内容をドキュメンテーションコメントとして残すといった一連の流れをソースコード上で行うことができます。 Javadocは、標準クラスライブラリのリファレンスドキュメントを見れば、クラスやメソッドの使い方を理解するのにとても役に立つことはわかります。しかし、システム開発現場のドキュメントとしては、それだけでは不十分です。 Javadocに足りないのは「ソースコードが正しいか」ということを表現できないことです。正しさを確認するには2つの視点があります。1つは「どんなシステムを作るのか」という視点。もう1つは「どのように検証するのか」
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
testearly.com
IBM Developer