Begin documenting std and add doc generation using naturaldocs

Naturaldocs isn't really that great but it seems easier to get
something working than with doxygen, for which we would need to
convert rust code to something C++ish. We probably want to just
write a rustdoc utility at some point.

Author: brson

configure

@@ -387,7 +387,8 @@ rm -f config.mk.bak
 
 step_msg "making directories"
 for i in \
-    doc \
+    doc doc/std \
+    nd nd/std \
     rt rt/isaac rt/bigint rt/sync rt/test rt/arch/i386 \
     rt/libuv rt/libuv/src/ares rt/libuv/src/eio rt/libuv/src/ev \
     rustllvm dl \

doc/Languages.txt

@@ -0,0 +1,124 @@
+Format: 1.51
+
+# This is the Natural Docs languages file for this project.  If you change
+# anything here, it will apply to THIS PROJECT ONLY.  If you'd like to change
+# something for all your projects, edit the Languages.txt in Natural Docs'
+# Config directory instead.
+
+
+# You can prevent certain file extensions from being scanned like this:
+# Ignore Extensions: [extension] [extension] ...
+
+
+#-------------------------------------------------------------------------------
+# SYNTAX:
+#
+# Unlike other Natural Docs configuration files, in this file all comments
+# MUST be alone on a line.  Some languages deal with the # character, so you
+# cannot put comments on the same line as content.
+#
+# Also, all lists are separated with spaces, not commas, again because some
+# languages may need to use them.
+#
+# Language: [name]
+# Alter Language: [name]
+#    Defines a new language or alters an existing one.  Its name can use any
+#    characters.  If any of the properties below have an add/replace form, you
+#    must use that when using Alter Language.
+#
+#    The language Shebang Script is special.  It's entry is only used for
+#    extensions, and files with those extensions have their shebang (#!) lines
+#    read to determine the real language of the file.  Extensionless files are
+#    always treated this way.
+#
+#    The language Text File is also special.  It's treated as one big comment
+#    so you can put Natural Docs content in them without special symbols.  Also,
+#    if you don't specify a package separator, ignored prefixes, or enum value
+#    behavior, it will copy those settings from the language that is used most
+#    in the source tree.
+#
+# Extensions: [extension] [extension] ...
+# [Add/Replace] Extensions: [extension] [extension] ...
+#    Defines the file extensions of the language's source files.  You can
+#    redefine extensions found in the main languages file.  You can use * to
+#    mean any undefined extension.
+#
+# Shebang Strings: [string] [string] ...
+# [Add/Replace] Shebang Strings: [string] [string] ...
+#    Defines a list of strings that can appear in the shebang (#!) line to
+#    designate that it's part of the language.  You can redefine strings found
+#    in the main languages file.
+#
+# Ignore Prefixes in Index: [prefix] [prefix] ...
+# [Add/Replace] Ignored Prefixes in Index: [prefix] [prefix] ...
+#
+# Ignore [Topic Type] Prefixes in Index: [prefix] [prefix] ...
+# [Add/Replace] Ignored [Topic Type] Prefixes in Index: [prefix] [prefix] ...
+#    Specifies prefixes that should be ignored when sorting symbols in an
+#    index.  Can be specified in general or for a specific topic type.
+#
+#------------------------------------------------------------------------------
+# For basic language support only:
+#
+# Line Comments: [symbol] [symbol] ...
+#    Defines a space-separated list of symbols that are used for line comments,
+#    if any.
+#
+# Block Comments: [opening sym] [closing sym] [opening sym] [closing sym] ...
+#    Defines a space-separated list of symbol pairs that are used for block
+#    comments, if any.
+#
+# Package Separator: [symbol]
+#    Defines the default package separator symbol.  The default is a dot.
+#
+# [Topic Type] Prototype Enders: [symbol] [symbol] ...
+#    When defined, Natural Docs will attempt to get a prototype from the code
+#    immediately following the topic type.  It stops when it reaches one of
+#    these symbols.  Use \n for line breaks.
+#
+# Line Extender: [symbol]
+#    Defines the symbol that allows a prototype to span multiple lines if
+#    normally a line break would end it.
+#
+# Enum Values: [global|under type|under parent]
+#    Defines how enum values are referenced.  The default is global.
+#    global       - Values are always global, referenced as 'value'.
+#    under type   - Values are under the enum type, referenced as
+#               'package.enum.value'.
+#    under parent - Values are under the enum's parent, referenced as
+#               'package.value'.
+#
+# Perl Package: [perl package]
+#    Specifies the Perl package used to fine-tune the language behavior in ways
+#    too complex to do in this file.
+#
+#------------------------------------------------------------------------------
+# For full language support only:
+#
+# Full Language Support: [perl package]
+#    Specifies the Perl package that has the parsing routines necessary for full
+#    language support.
+#
+#-------------------------------------------------------------------------------
+
+# The following languages are defined in the main file, if you'd like to alter
+# them:
+#
+#    Text File, Shebang Script, C/C++, C#, Java, JavaScript, Perl, Python,
+#    PHP, SQL, Visual Basic, Pascal, Assembly, Ada, Tcl, Ruby, Makefile,
+#    ActionScript, ColdFusion, R, Fortran
+
+# If you add a language that you think would be useful to other developers
+# and should be included in Natural Docs by default, please e-mail it to
+# languages [at] naturaldocs [dot] org.
+
+
+Language: Rust
+
+   Extensions: rc rs
+   Line Comment: //
+   Block Comment: /* */
+   Package Separator: ::
+   Function Prototype Enders: ; {
+   Type Prototype Enders: ; }
+   Class Prototype Enders: {

doc/Topics.txt

@@ -0,0 +1,159 @@
+Format: 1.51
+
+# This is the Natural Docs topics file for this project.  If you change anything
+# here, it will apply to THIS PROJECT ONLY.  If you'd like to change something
+# for all your projects, edit the Topics.txt in Natural Docs' Config directory
+# instead.
+
+
+# If you'd like to prevent keywords from being recognized by Natural Docs, you
+# can do it like this:
+# Ignore Keywords: [keyword], [keyword], ...
+#
+# Or you can use the list syntax like how they are defined:
+# Ignore Keywords:
+#    [keyword]
+#    [keyword], [plural keyword]
+#    ...
+
+
+#-------------------------------------------------------------------------------
+# SYNTAX:
+#
+# Topic Type: [name]
+# Alter Topic Type: [name]
+#    Creates a new topic type or alters one from the main file.  Each type gets
+#    its own index and behavior settings.  Its name can have letters, numbers,
+#    spaces, and these charaters: - / . '
+#
+# Plural: [name]
+#    Sets the plural name of the topic type, if different.
+#
+# Keywords:
+#    [keyword]
+#    [keyword], [plural keyword]
+#    ...
+#    Defines or adds to the list of keywords for the topic type.  They may only
+#    contain letters, numbers, and spaces and are not case sensitive.  Plural
+#    keywords are used for list topics.  You can redefine keywords found in the
+#    main topics file.
+#
+# Index: [yes|no]
+#    Whether the topics get their own index.  Defaults to yes.  Everything is
+#    included in the general index regardless of this setting.
+#
+# Scope: [normal|start|end|always global]
+#    How the topics affects scope.  Defaults to normal.
+#    normal        - Topics stay within the current scope.
+#    start         - Topics start a new scope for all the topics beneath it,
+#                    like class topics.
+#    end           - Topics reset the scope back to global for all the topics
+#                    beneath it.
+#    always global - Topics are defined as global, but do not change the scope
+#                    for any other topics.
+#
+# Class Hierarchy: [yes|no]
+#    Whether the topics are part of the class hierarchy.  Defaults to no.
+#
+# Page Title If First: [yes|no]
+#    Whether the topic's title becomes the page title if it's the first one in
+#    a file.  Defaults to no.
+#
+# Break Lists: [yes|no]
+#    Whether list topics should be broken into individual topics in the output.
+#    Defaults to no.
+#
+# Can Group With: [type], [type], ...
+#    Defines a list of topic types that this one can possibly be grouped with.
+#    Defaults to none.
+#-------------------------------------------------------------------------------
+
+# The following topics are defined in the main file, if you'd like to alter
+# their behavior or add keywords:
+#
+#    Generic, Class, Interface, Section, File, Group, Function, Variable,
+#    Property, Type, Constant, Enumeration, Event, Delegate, Macro,
+#    Database, Database Table, Database View, Database Index, Database
+#    Cursor, Database Trigger, Cookie, Build Target
+
+# If you add something that you think would be useful to other developers
+# and should be included in Natural Docs by default, please e-mail it to
+# topics [at] naturaldocs [dot] org.
+
+
+#Topic Type: Crate
+
+#   Plural: Crates
+#   Scope: Always Global
+
+#   Keywords:
+#      crate, crates
+
+Topic Type: Syntax Extension
+
+   Plural: Syntax Extensions
+   Scope: Always Global
+
+   Keywords:
+      syntax extension, syntax extensions
+
+#Alter Topic Type: Class
+
+#   Keywords:
+#      object, objects
+#      tag, tags
+#      resource, resources
+
+Topic Type: Module
+   Plural: Modules
+   Scope: Start
+   Class Hierarchy: Yes
+   Page Title If First: Yes
+
+   Keywords:
+      module, modules
+
+Topic Type: Object
+   Plural: Objects
+   Scope: Start
+   Class Hierarchy: Yes
+
+   Keywords:
+      obj, objs
+
+Topic Type: Tag
+   Plural: Tags
+   Scope: Start
+   Class Hierarchy: Yes
+
+   Keywords:
+      tag, tags
+
+#Alter Topic Type: Function
+
+#   Scope: Start
+#      predicate, predicates
+
+#   Ignore Keywords:
+#      method, methods
+#   Keywords:
+#      variant, variants
+
+Topic Type: Variant
+
+   Plural: Variants
+   Keywords:
+      variant, variants
+
+#Alter Topic Type: Type
+
+#    Keywords:
+#       tag, tags
+
+Topic Type: Predicate
+
+   Plural: Predicates
+   Break Lists: Yes
+
+   Keywords:
+      predicate, predicates

mk/docs.mk

@@ -19,3 +19,16 @@ doc/%.html: %.texi doc/version.texi
 docsnap: doc/rust.pdf
 	@$(call E, snap: doc/rust-$(shell date +"%Y-%m-%d")-snap.pdf)
 	$(Q)mv $< doc/rust-$(shell date +"%Y-%m-%d")-snap.pdf
+
+doc/std/index.html: nd/std/Languages.txt nd/std/Topics.txt \
+                    $(STDLIB_CRATE) $(STDLIB_INPUTS)
+	@$(call E, naturaldocs: $@)
+	naturaldocs -i $(S)src/lib -o HTML doc/std -p nd/std -r
+
+nd/std/Languages.txt: $(S)doc/Languages.txt
+	@$(call E, cp: $@)
+	$(Q)cp $< $@
+
+nd/std/Topics.txt: $(S)doc/Topics.txt
+	@$(call E, cp: $@)
+	$(Q)cp $< $@

src/lib/bitv.rs

@@ -1,3 +1,8 @@
+/*
+Module: bitv
+
+Bitvectors.
+*/
 
 export t;
 export create;
@@ -23,12 +28,26 @@ export eq_vec;
 //        an optimizing version of this module that produces a different obj
 //        for the case where nbits <= 32.
 
+/*
+Type: t
+
+The bitvector type.
+*/
 type t = @{storage: [mutable uint], nbits: uint};
 
 
 // FIXME: this should be a constant once they work
 fn uint_bits() -> uint { ret 32u + (1u << 32u >> 27u); }
 
+/*
+Function: create
+
+Constructs a bitvector.
+
+Parameters:
+nbits - The number of bits in the bitvector
+init - If true then the bits are initialized to 1, otherwise 0
+*/
 fn create(nbits: uint, init: bool) -> t {
     let elt = if init { !0u } else { 0u };
     let storage = vec::init_elt_mut::<uint>(elt, nbits / uint_bits() + 1u);

src/lib/box.rs

@@ -1,6 +1,15 @@
+/*
+Module: box
+*/
+
 
 export ptr_eq;
 
+/*
+Function: ptr_eq
+
+Determine if two shared boxes point to the same object
+*/
 fn ptr_eq<T>(a: @T, b: @T) -> bool {
     let a_ptr: uint = unsafe::reinterpret_cast(a);
     let b_ptr: uint = unsafe::reinterpret_cast(b);

src/lib/char.rs

@@ -1,3 +1,18 @@
+/*
+Module: char
+
+Utilities for manipulating the char type
+*/
+
+/*
+Function: is_whitespace
+
+Indicates whether a character is whitespace.
+
+Whitespace characters include space (U+0020), tab (U+0009), line feed
+(U+000A), carriage return (U+000D), and a number of less common
+ASCII and unicode characters.
+*/
 pure fn is_whitespace(c: char) -> bool {
     const ch_space: char = '\u0020';
     const ch_ogham_space_mark: char = '\u1680';