From 89b349cad5d13b5e8f3dfccb1e554245120e4cc2 Mon Sep 17 00:00:00 2001 From: Dan Korostelev Date: Tue, 14 Oct 2014 01:57:41 +0400 Subject: [PATCH] add guideline on documentation style (closes #11) --- HOWTO.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/HOWTO.md b/HOWTO.md index 98bed016..eff9fa6b 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -158,6 +158,23 @@ Note that combined with `haxe.EitherType` (described above), `@:enum abstract`s } ``` +## API Documenting + +We use API documentation style found in Haxe standard library and copy upstream API documentation text to externs (applying some minor editing/reformatting to it). + +Example of Haxe standard library style: + +```haxe +/** + Does that and returns this. + + Some more info about using argument `a` and `b`. +**/ +static function doStuff(a:Int, b:String):Void; +``` + +Note that node.js API documentation often describes types of variables which is mostly redundant in Haxe, so these parts can be removed. + ## Tricks and hints TODO (dealing with keywords, `untyped __js__`, inline methods and properties on extern classes)