Determine best default headerblock format

[DamonOehlman]

Hey All,

Working on this as a standalone project which is designed to bring header block comment generation to Interleave. At the moment, the code is still a work in progress, but some functionality is already there. Before I go too far though, I'd love to have some feedback on what people think should be in a source file headerblock.

Here are some examples from around the web:

jquery

/*!
 * jQuery JavaScript Library v1.8.2
 * http://jquery.com/
 *
 * Includes Sizzle.js
 * http://sizzlejs.com/
 *
 * Copyright 2012 jQuery Foundation and other contributors
 * Released under the MIT license
 * http://jquery.org/license
 *
 * Date: Thu Sep 20 2012 21:13:05 GMT-0400 (Eastern Daylight Time)
 */

eve

// ┌──────────────────────────────────────────────────────────────────────────────────────┐ \\
// │ Eve 0.3.5 - JavaScript Events Library                                                │ \\
// ├──────────────────────────────────────────────────────────────────────────────────────┤ \\
// │ Copyright (c) 2008-2012 Dmitry Baranovskiy (http://dmitry.baranovskiy.com/)          │ \\
// │ Licensed under the MIT (http://www.opensource.org/licenses/mit-license.php) license. │ \\
// └──────────────────────────────────────────────────────────────────────────────────────┘ \\

and there are plenty of others.

My general thoughts are that the headerblock should not only be easy on the eye for a human, but also something that is potentially machine readable. So potentially incorporating a YAML section for metadata is one thing I've been considering.

Here are some early examples of the kind of thing I'm thinking about:

/* ~libraryname~
 * 
 * Multiline description of the library
 * 
 * Copyright line?
 * 
 * ---meta
 * version: 0.0.1 (semver)
 * build: (build date - isoformat)
 *
 * licenses:
 *     - MIT
 * 
 * maintainers:
 *     - Fred Flintstone <[email protected]>
 * 
 * contributors:
 *     - Barney Rubble <[email protected]>
 * 
 */ 

The leading comment line incorporating a tilda (~) would be used to indicate that the comment block is potentially machine parseable.

Thoughts?