bu da işine yarayabilir (: ### Documentation Comment Standards When writing or editing code, always add documentation comments using the native DocBlock standard of the language in question. Do not invent custom formats. Use the following per language: - **Java** → Javadoc (`/** ... */` with `@param`, `@return`, `@throws`) - **JavaScript** → JSDoc (`/** ... */` with `@param {type}`, `@returns`) - **TypeScript** → TSDoc (JSDoc-compatible; omit redundant type annotations already expressed in the type system) - **PHP** → PHPDoc / PSR-5 draft conventions (`@param`, `@return`, `@throws`) - **Python** → PEP 257 docstrings; prefer Google style (or match the project's existing style: NumPy / reStructuredText for Sphinx) - **C / C ** → Doxygen (`/** ... */` or `///` with `@brief`, `@param`) - **C#** → XML documentation comments (`///` with `<summary>`, `<param>`, `<returns>`) — consumed by IntelliSense and DocFX - **Go** → godoc conventions: plain comment immediately above the declaration, starting with the identifier's name; no tags - **Rust** → rustdoc (`///` for items, `//!` for modules); Markdown body with `# Examples`, `# Panics`, `# Errors` sections - **Kotlin** → KDoc (`/** ... */` with `@param`, `@return`; Markdown body) - **Swift** → Swift-flavored Markdown / DocC (`///` with `- Parameter:`, `- Returns:`, `- Throws:`) - **Dart** → dartdoc (`///` with Markdown; reference members with `[name]`) - **Scala** → Scaladoc (`/** ... */`) - **Ruby** → YARD (`@param`, `@return`) or RDoc, matching the project - **Elixir** → `@moduledoc` / `@doc` attributes (ExDoc, Markdown) - **Haskell** → Haddock (`-- |` and `-- ^`) - **Perl** → POD (`=head1`, `=cut`) - **R** → roxygen2 (`#'` with `@param`, `@return`, `@export`) - **Lua** → LDoc / LuaDoc (`---` with `@param`, `@return`) - **Julia** → docstrings (Markdown string placed directly above the definition) Documentation Comment rules: - Match the documentation style already present in the project before defaulting to the standards above. - Document all public/exported APIs; private helpers only when non-obvious. - Keep descriptions concise: one summary line, then details only if needed. - Document parameters, return values, thrown errors/exceptions, and side effects. - Do not restate types in prose when the language's type system already declares them (TypeScript, Rust, Go, Kotlin, etc.).

OSSのプログラムってドキュメント生成のためにJavaDocの形式コメントめっちゃ書いてるので、それを学習した結果かな？

There is a JEP pending to bring admonitions to Javadoc! openjdk.org/jeps/8363700 They call it "notes", but it's effectively the admonition concept as known from Sphinx or AsciiDoc. APIdia found its own solution for notes in Javadoc some years earlier: #java #javadoc #apidia #jvm

CustomCrafterAPI 5.2.1 をリリースしました - Java から使うときに一部の関数を自然な形で使えるようになりました - Javadoc を追加しました GitHub: github.com/Sakaki-Aruka/cust… Modrinth: modrinth.com/plugin/custom-c… #minecraft #minecraftserver #plugin #modrinth

Javadoc を出力できるにはできるけど、本来 KDoc を生成するためのソフトで無理くりやってるのでちょっとおかしなところがある

Java26 の日本語 JavaDoc 出てますね！ありがたいです。 docs.oracle.com/javase/jp/26…

今日は気合と根性のAIが作ったコード解析。 昨日は1行につき行末にコメントつけてくれて、Grepした時丁度いいなって思ってたのに、なぜか一番めんどくさく量の多いファイルはさぼってた。コメントを付けなおしてもらったら、なぜかここだけJavadoc風に…いらん🥵AIも相当気分屋🥲

Ever needed to use an MS Access database via #JDBC? This once was a hassle via ODBC-JDBC bridge with platform-dependent driver. Nowadays, there is a pure #Java solution: With UCanAccess, you can access Access :) What's best: Latest API docs are available on #APIdia! #javadoc

UCanAccess is a pure #Java library that provides #JDBC read- and write-access to various versions of Microsoft Access databases: With UCanAccess you can access Access :) API reference documentation of its latest release 5.1.5 is now on #APIdia! (link in the comments) #javadoc

セッションでは触れませんでしたが JavaDoc Search Specification には JavaDocの検索機能の仕様が docs.oracle.com/en/java/java…

JavaDoc 再入門 ―AI時代のドキュメント戦略― セッション資料です speakerdeck.com/nagise/javad… #JJUG_CCC #JJUG_CCC_A

なぎせさんのjavadocセッションー！ - Java23から///でmd - javadocガイドに全部解説されてると思いきやされてないらしいw - ブロックタグとインラインタグがある - ドックレットで独自拡張できる #jjug_ccc #jjug_ccc_a

Wer große APIs dokumentiert, kennt das Problem: Tutorials funktionieren gut — Referenzdokumentation oft weniger. Orientierung geht verloren. Willst du APIs schneller verstehen? @stewori analysiert #Javadoc, #Doxygen & Sphinx mit #APIdia. Lies: javapro.io/de/apidia-eine-ne… @apidia_net

要するに「コードが何をしているか」ではなく、 「このシステムがどういう存在で、何を守るべきで、どんな制約の中で生きているか」を言語化し続けるイメージなんですね。 例でJavadoc出してしまって申し訳ないです。 関数レベルのJavaDocみたいなin/outじゃなくて、機能一覧レベルでのin/out・不変条件・トレードオフを積んでいく感じで合ってますか？ コードは「読まない消耗品」として扱って、本当の資産はAIが即座に理解できる高抽象度の文脈の方に置く。 大規模LLMが普通に使える今、確かに従来の「人間が全部読む前提」ドキュメントは陳腐化しつつあるなと。 この方向性、かなり刺さりました。ありがとうございます。

JavaDocはローレベルすぎて冗長なのでもっと抽象度の高い仕様書レベルの文書を積んでいくほうがいいと思います。コード規約とかlintはもう不要で型検査とテストでカバーします。

„Gut dokumentiert“ hilft wenig, wenn Entwickler die Struktur einer API nicht mehr erkennen können. Das kritisiert @stewori an modernen Doku-Systemen! Arbeitest du mit großen APIs? Dann lohnt sich der Blick auf #APIdia: javapro.io/de/apidia-eine-ne… #Doxygen #Javadoc @doxygen