basic header docs of all public modules

blendish.d

@@ -25,10 +25,6 @@ THE SOFTWARE.
 // Ketmar // Invisible Vector <ketmar@ketmar.no-ip.org>
 /**
 
-Revision 6 (2014-09-21)
-
-Summary
-
 Blendish is a small collection of drawing functions for NanoVega, designed to
 replicate the look of the Blender 2.5+ User Interface. You can use these
 functions to theme your UI library. Several metric constants for faithful
@@ -54,6 +50,9 @@ to the equivalent of 72 dpi in the Blender system settings.
 
 Support for label truncation is missing. Text rendering breaks when widgets are
 too short to contain their labels.
+
+Version:
+	Revision 6 (2014-09-21)
 */
 module arsd.blendish;
 private:

bmp.d

@@ -1,4 +1,7 @@
-/// bmp impl for MemoryImage
+/++
+	Basic .bmp file format implementation for [arsd.color.MemoryImage].
+	Compare with [arsd.png] basic functionality.
++/
 module arsd.bmp;
 
 import arsd.color;
@@ -6,6 +9,7 @@ import arsd.color;
 //version = arsd_debug_bitmap_loader;
 
 
+/// Reads a .bmp file from the given `filename`
 MemoryImage readBmp(string filename) {
 	import core.stdc.stdio;
 
@@ -22,6 +26,7 @@ MemoryImage readBmp(string filename) {
 	return readBmpIndirect(&specialFread);
 }
 
+/// Reads a bitmap out of an in-memory array of data. For example, that returned from [std.file.read].
 MemoryImage readBmp(in ubyte[] data) {
 	const(ubyte)[] current = data;
 	void specialFread(void* tgt, size_t size) {
@@ -37,6 +42,7 @@ MemoryImage readBmp(in ubyte[] data) {
 	return readBmpIndirect(&specialFread);
 }
 
+/// Reads using a delegate to read instead of assuming a direct file
 MemoryImage readBmpIndirect(scope void delegate(void*, size_t) fread) {
 	uint read4()  { uint what; fread(&what, 4); return what; }
 	ushort read2(){ ushort what; fread(&what, 2); return what; }
@@ -358,6 +364,8 @@ MemoryImage readBmpIndirect(scope void delegate(void*, size_t) fread) {
 	assert(0);
 }
 
+/// Writes the `img` out to `filename`, in .bmp format. Writes [TrueColorImage] out
+/// as a 24 bmp and [IndexedImage] out as an 8 bit bmp. Drops transparency information.
 void writeBmp(MemoryImage img, string filename) {
 	import core.stdc.stdio;
 	FILE* fp = fopen((filename ~ "\0").ptr, "wb".ptr);

cidr.d

@@ -1,4 +1,4 @@
-///
+/// Some helper functions for using CIDR format network ranges.
 module arsd.cidr;
 
 ///

color.d

@@ -1,4 +1,6 @@
-///
+/++
+	Base module for working with colors and in-memory image pixmaps.
++/
 module arsd.color;
 
 @safe:

csv.d

@@ -1,10 +1,10 @@
-///
+/// My old csv code. Extremely basic functionality.
 module arsd.csv;
 
 import std.string;
 import std.array;
 
-///
+/// Returns the array of csv rows from the given in-memory data (the argument is NOT a filename).
 string[][] readCsv(string data) {
 	data = data.replace("\r\n", "\n");
 	data = data.replace("\r", "");
@@ -65,7 +65,7 @@ string[][] readCsv(string data) {
 	return records;
 }
 
-///
+/// Formats the given rows into csv format. Use like `std.file.write(toCsv(...));`
 string toCsv(string[][] rows) {
 	string data;
 

dbus.d

@@ -1,5 +1,5 @@
 /++
-	A module mostly copied from https://github.com/trishume/ddbus
+	A module mostly copied from https://github.com/trishume/ddbus to help access the C dbus library on Linux.
 +/
 module arsd.dbus;
 

email.d

@@ -1,4 +1,6 @@
-///
+/++
+	Create MIME emails with things like HTML, attachments, and send with convenience wrappers around std.net.curl's SMTP function, or read email from an mbox file.
++/
 module arsd.email;
 
 import std.net.curl;

engine.d

@@ -1,7 +1,7 @@
 // This code is D 1.0
 
-/***
+/**
-	The base class from which a game engine should inherit.
+	Part of my old D 1.0 game helper code that used SDL. I keep it compiling on new D compilers too, but it is not meant to be used in new projects.
 
 	Version: 1.0
 	License: GNU General Public License

english.d

@@ -1,6 +1,11 @@
-///
+/// A few helper functions for manipulating English words. Extremely basic.
 module arsd.english;
 
+/++
+	Given a non-one `count` argument, will attempt to return the plural version of `word`. Only handles basic cases. If count is one, simply returns the word.
+
+	I originally wrote this for cases like `You have {n} {messages|plural(n)}` in web templates.
++/
 string plural(int count, string word, string pluralWord = null) {
 	if(count == 1 || word.length == 0)
 		return word; // it isn't actually plural
@@ -21,6 +26,7 @@ string plural(int count, string word, string pluralWord = null) {
 	}
 }
 
+/// Given an integer, tries to write out the long form number. For example, -5 becomes "negative five".
 string numberToEnglish(long number) {
 	string word;
 	if(number == 0)

eventloop.d

@@ -1,4 +1,4 @@
-/// crappy event loop for linux
+/// My old event loop helper library for Linux. Not recommended for new projects.
 module arsd.eventloop;
 
 version(linux):

gamehelpers.d

@@ -4,7 +4,7 @@
 
 /++
 	An add-on for simpledisplay.d, joystick.d, and simpleaudio.d
-	that includes helper functions for writing games (and perhaps
+	that includes helper functions for writing simple games (and perhaps
 	other multimedia programs). Whereas simpledisplay works with
 	an event-driven framework, gamehelpers always uses a consistent
 	timer for updates.

hmac.d

@@ -1,8 +1,9 @@
-///
+/// Implementation of the HMAC algorithm. Do not use on new things because [std.digest.hmac] now exists in Phobos.
 module arsd.hmac;
 
 // FIXME: the blocksize is correct for MD5, SHA1, and SHA256 but not generally
 // it should really be gotten from the hash
+///
 auto hmac(alias hash, size_t blocksize = 64)(in void[] keyv, in void[] messagev) {
 
 	const(ubyte)[] key = cast(const(ubyte)[]) keyv;

html.d

@@ -1,5 +1,5 @@
 /**
-	This module includes functions to work with HTML and CSS.
+	This module includes functions to work with HTML and CSS in a more specialized manner than [arsd.dom]. Most of this is obsolete from my really old D web stuff, but there's still some useful stuff. View source before you decide to use it, as the implementations may suck more than you want to use.
 
 	It publically imports the DOM module to get started.
 	Then it adds a number of functions to enhance html
@@ -178,6 +178,7 @@ Element sanitizedHtml(/*in*/ Element userContent, string idPrefix = null, HtmlFe
 	return div;
 }
 
+///
 Element sanitizedHtml(in Html userContent, string idPrefix = null, HtmlFeatures allow = HtmlFeatures.links | HtmlFeatures.images | HtmlFeatures.css) {
 	auto div = Element.make("div");
 	div.innerHTML = userContent.source;
@@ -190,6 +191,7 @@ string sanitizeCss(string css) {
 	return css.replace("expression", "");
 }
 
+///
 string sanitizeUrl(string url) {
 	// FIXME: support other options; this is more restrictive than it has to be
 	if(url.startsWith("http://") || url.startsWith("https://") || url.startsWith("//"))
@@ -211,6 +213,9 @@ string recommendedBasicCssForUserContent = `
 	}
 `;
 
+/++
+	Given arbitrary user input, find links and add `<a href>` wrappers, otherwise just escaping the rest of it for HTML display.
++/
 Html linkify(string text) {
 	auto div = Element.make("div");
 
@@ -243,7 +248,7 @@ Html linkify(string text) {
 	return Html(div.innerHTML);
 }
 
-// your things should already be encoded
+/// Given existing encoded HTML, turns \n\n into `<p>`.
 Html paragraphsToP(Html html) {
 	auto text = html.source;
 	string total;
@@ -261,6 +266,7 @@ Html paragraphsToP(Html html) {
 	return Html(total);
 }
 
+/// Given user text, converts newlines to `<br>` and encodes the rest.
 Html nl2br(string text) {
 	auto div = Element.make("div");
 
@@ -283,6 +289,7 @@ bool appearsToBeHtml(string src) {
 	return cast(bool) match(src, `.*\<[A-Za-z]+>.*`);
 }
 
+/// Get the favicon out of a document, or return the default a browser would attempt if it isn't there.
 string favicon(Document document) {
 	auto item = document.querySelector("link[rel~=icon]");
 	if(item !is null)
@@ -290,6 +297,7 @@ string favicon(Document document) {
 	return "/favicon.ico"; // it pisses me off that the fucking browsers do this.... but they do, so I will too.
 }
 
+///
 Element checkbox(string name, string value, string label, bool checked = false) {
 	auto lbl = Element.make("label");
 	auto input = lbl.addChild("input");

htmltotext.d

@@ -1,4 +1,8 @@
-///
+/++
+	Converts HTML to plain text. Can also output VT escape sequences for terminal output.
+
+	The exact output of this is subject to change - it is just what appears nice for me. (I actually use this on my personal email setup.)
++/
 module arsd.htmltotext;
 
 import arsd.dom;

htmlwidget.d

@@ -1,4 +1,7 @@
 /**
+	My old toy html widget build out of my libraries. Not great, you probably don't want to use it.
+
+
 	This module has a lot of dependencies
 
 	dmd yourapp.d arsd/htmlwidget.d arsd/simpledisplay.d arsd/curl.d arsd/color.d arsd/dom.d arsd/characterencodings.d arsd/imagedraft.d -J. -version=browser

http.d

@@ -1,9 +1,9 @@
 /++
-	Old version of my http implementation.
+	OBSOLETE: Old version of my http implementation. Do not use this, instead use [arsd.http2].
 
 	I no longer work on this, use http2.d instead.
 +/
-deprecated module arsd.http;
+/*deprecated*/ module arsd.http; // adrdox apparently loses the comment above with deprecated, i need to fix that over there.
 
 import std.socket;
 

image.d

@@ -1,4 +1,6 @@
-/// this file imports all available image decoders, and provides convenient functions to load image regardless of it's format.
+/++
+	This file imports all available image decoders in the arsd library, and provides convenient functions to load image regardless of it's format. Main functions: [loadImageFromFile] and [loadImageFromMemory].
++/
 module arsd.image;
 
 public import arsd.color;

joystick.d

@@ -1,5 +1,13 @@
-/**
+/++
 
+	Provides a polling-based API to use gamepads/joysticks on Linux and Windows.
+
+	Pass `-version=ps1_style` or `-version=xbox_style` to pick your API style - the constants will use the names of the buttons on those controllers and attempt to emulate the other. ps1_style is compatible with more hardware and thus the default. XBox controllers work with either, though.
+
+	The docs for this file are quite weak, I suggest you view source of [arsd.gamehelers] for an example of how it might be used.
++/
+
+/*
 	FIXME: a simple function to integrate with sdpy event loop. templated function
 
 	HIGH LEVEL NOTES

jpeg.d

@@ -36,6 +36,7 @@
 // http://vision.ai.uiuc.edu/~dugad/research/dct/index.html
 /**
  * Loads a JPEG image from a memory buffer or a file.
+ *
  * req_comps can be 1 (grayscale), 3 (RGB), or 4 (RGBA).
  * On return, width/height will be set to the image's dimensions, and actual_comps will be set to the either 1 (grayscale) or 3 (RGB).
  * Requesting a 8 or 32bpp image is currently a little faster than 24bpp because the jpeg_decoder class itself currently always unpacks to either 8 or 32bpp.

jpg.d

@@ -1,4 +1,4 @@
-///
+/// Reads a jpg header without reading the rest of the file. Use [arsd.jpeg] for an actual image loader if you need actual data, but this is kept around for times when you only care about basic info like image dimensions.
 module arsd.jpg;
 
 import std.typecons;

libssh2.d

@@ -1,7 +1,8 @@
-/// Small wrapper for libssh2
+/++
-/// just link with it on Linux
+	Minimal bindings for libssh2. (just what I needed for my terminal emulator, but I'd accept more, and even wrappers if you wanted to.)
-/// it'll need a couple dlls and a lib on windows.
 
+	Just link with it on Linux, but it'll need a couple dlls and a lib on windows.
++/
 module arsd.libssh2;
 
 version(libssh_example)

midi.d

@@ -1,5 +1,5 @@
 /**
-	This file is a port of some old C code I had.
+	This file is a port of some old C code I had for reading and writing .mid files. Not much docs, but viewing the source may be helpful.
 
 	I'll eventually refactor it into something more D-like
 */

mssql.d

@@ -1,6 +1,9 @@
 // NOTE: I haven't even tried to use this for a test yet!
 // It's probably godawful, if it works at all.
-///
+/++
+	Implementation of [arsd.database.Database] interface for
+	Microsoft SQL Server, via ODBC.
++/
 module arsd.mssql;
 
 version(Windows):
@@ -15,8 +18,9 @@ import std.exception;
 import core.sys.windows.sql;
 import core.sys.windows.sqlext;
 
+///
 class MsSql : Database {
-	// dbname = name  is probably the most common connection string
+	/// auto db = new MsSql("Driver={SQL Server Native Client 10.0};Server=<host>[\\<optional-instance-name>];Database=dbtest;Trusted_Connection=Yes")
 	this(string connectionString) {
 		SQLAllocHandle(SQL_HANDLE_ENV, cast(void*)SQL_NULL_HANDLE, &env);
 		enforce(env !is null);

mysql.d

@@ -1,5 +1,5 @@
 /++
-	Implementation of the `arsd.database.Database|database` interface for
+	Implementation of the [arsd.database.Database] interface for
 	accessing MySQL (and MariaDB) databases. Uses the official MySQL client
 	library, and thus needs that installed to compile and run.
 

oauth.d

@@ -1,4 +1,4 @@
-///
+/// Implementations of OAuth 1.0 server and client. You probably don't need this anymore; I haven't used it for years.
 module arsd.oauth;
 
 import arsd.curl;

png.d

@@ -1,4 +1,4 @@
-/// PNG file handling for color.d's Image interfaces
+/// PNG file read and write. Leverages color.d's Image interfaces for interop.
 module arsd.png;
 
 import core.memory;

postgres.d

@@ -1,4 +1,4 @@
-/// minimal libpq wrapper
+/// Uses libpq implement the [arsd.database.Database] interface.
 module arsd.postgres;
 pragma(lib, "pq");
 

rpc.d

@@ -1,3 +1,4 @@
+/// I never finished this. The idea is to use CT reflection to make calling another process feel as simple as calling in-process objects. Will come eventually but no promises.
 module arsd.rpc;
 
 /*

rtud.d

@@ -1,6 +1,7 @@
 /**
-	This provides a kind of real time updates that can be consumed
+	OBSOLETE: This provides a kind of real time updates that can be consumed
-	by javascript (and probably other things eventually).
+	by javascript (and probably other things eventually). Superseded by
+	new functionality built into [arsd.cgi].
 
 	First, you compile the server app. dmd -version=standalone_rtud -version=rtud_daemon
 

screen.d

@@ -1,5 +1,8 @@
 // This code is D 1.0
 
+/**
+	Part of my old D 1.0 game helper code that used SDL. I keep it compiling on new D compilers too, but it is not meant to be used in new projects.
+*/
 module arsd.screen;
 
 import sdl.SDL;

sha.d

@@ -1,4 +1,4 @@
-/// homemade sha 1 and sha2 impls. beware of bugs.
+/// Homemade SHA 1 and SHA 2 implementations. Beware of bugs - you should probably use [std.net.digest] instead. Kept more for historical curiosity than anything else.
 module arsd.sha;
 
 /*

sqlite.d

@@ -1,4 +1,6 @@
 /**
+	SQLite implementation of the [arsd.database.Database] interface.
+
 	Compile with version=sqlite_extended_metadata_available
 	if your sqlite is compiled with the
 	 SQLITE_ENABLE_COLUMN_METADATA C-preprocessor symbol.
@@ -71,8 +73,10 @@ void main() {
 }
 */
 
+///
 class Sqlite : Database {
   public:
+	///
 	this(string filename, int flags = SQLITE_OPEN_READWRITE) {
 	/+
 		int error = sqlite3_open_v2(toStringz(filename), &db, flags, null);
@@ -112,6 +116,7 @@ class Sqlite : Database {
 		}
 	}
 
+	///
 	override void startTransaction() {
 		query("BEGIN TRANSACTION");
 	}
@@ -152,10 +157,12 @@ class Sqlite : Database {
 		return assumeUnique(m);
 	}
 
+	///
 	int affectedRows(){
 		return sqlite3_changes(db);
 	}
 
+	///
 	int lastInsertId(){
 		return cast(int) sqlite3_last_insert_rowid(db);
 	}

ttf.d

@@ -1,9 +1,9 @@
 /++
-	TrueType Font rendering.
+	TrueType Font rendering. Meant to be used with [arsd.simpledisplay], but it doesn't actually require that. Port of stb_truetype plus D wrappers for convenience.
 
 
-	Started as a copy of stb_truetype by Sean Barrett. It will be changing
+	Credits: Started as a copy of stb_truetype by Sean Barrett and ketmar helped
-	more later.
+	with expansions.
 +/
 module arsd.ttf;
 

vorbis.d

@@ -54,6 +54,9 @@
 // See end of file for full version history.
 // D translation by Ketmar // Invisible Vector
 // stolen by adam and module renamed.
+/++
+	Port of stb_vorbis to D. Provides .ogg audio file reading capabilities. See [arsd.simpleaudio] for code that can use this to actually load and play the file.
++/
 module arsd.vorbis;
 
 import core.stdc.stdio : FILE;

web.d

@@ -1,4 +1,6 @@
-/// magic web wrapper
+/++
+	Old magic web wrapper - one of my first applications of CT reflection. Given a class of fairly ordinary C code, it automatically creates HTML pages and forms, a Javascript file to access the functions from the client, and JSON based api responses. I do $(I not) recommend it for new projects though, as a replacement is now built into [arsd.cgi].
++/
 module arsd.web;