Update: A bug sometimes prevents Xcode from reading SwiftDocs for files other than the current file in a framework project, so you won't always see the doc comments in Quick Help or when Option-clicking a symbol. Hopefully the bug will be fixed.

Update #2: mattt of NSHipster fame heard from a little birdie that the doc comment format is adapted from reStructuredText. That gives us :param: and :returns: markers for the parameters and return values respectively.

Swift supports documentation comments. Give this a try:

///reads a line from standard input
///
///@param max:Int
/// specifies the number of bytes to read, 
/// must be at least 1 to account for null terminator.
///
///
///@return
/// the string, or nil if an error was encountered trying to read Stdin
func readln(max:Int = 8192) -> String? {
 ...
}

If you check your /Build/Intermediates/[project.build]/[config]/[project.build]/Objects-normal/[arch] folder, you will see a [projectname].swiftdoc file being generated.

Xcode is more than happy to read this swiftdoc file, so option-click on readln anywhere it appears in Xcode:

Unfortunately it does not yet respect the tags, but it does allow you to use single space indentation in the comment to give a nice large indentation in the Xcode popup.

edit: See the update; you can indicate parameters by :param:, one for each parameter on a separate line. Then use :returns: for the return value. Xcode does indeed recognize these and the Swift compiler generates a proper swiftdoc file.

Go forth and document!