auto merge of #6798 : alexcrichton/rust/doc-lints, r=pcwalton

These commits perform a variety of actions:

1. The linting of missing documentation has been consolidated under one `missing_doc` attribute, and many more things are linted about.
2. A test was added for linting missing documentation, which revealed a large number of corner cases in both linting and the `missing_doc` lint pass. Some notable edge cases:
  * When compiling with `--test`, all `missing_doc` warnings are suppressed
  * If any parent of the current item has `#[doc(hidden)]`, then the `missing_doc` warning is suppressed
3. Both the std and extra libraries were modified to `#[deny(missing_doc)]` by default.

I believe that the libraries are getting to the point where they're fairly well documented, and they should definitely stay that way. If developing a particular new module, it's easy enough to add `#[allow(missing_doc)]` at the top, but those should definitely be flags for removal in favor of actual documentation.

I added as much documentation as I could throughout std/extra, although I avoided trying to document things that I knew nothing about. I can't say that this lint pass will vouch for the quality of the documentation of std/extra, but it will certainly make sure that there's at least some describing words.

That being said, I may have a different opinion, so I don't mind amending these commits to turn off the lint by default for std/extra if people think otherwise.

1 files changed, 29 insertions, 0 deletions

diff --git a/src/libstd/ptr.rs b/src/libstd/ptr.rs
index 65375e410a6..0f7cf3f6bdf 100644
--- a/src/libstd/ptr.rs
+++ b/src/libstd/ptr.rs
@@ -120,6 +120,12 @@ pub unsafe fn copy_memory<T>(dst: *mut T, src: *const T, count: uint) {
     memmove64(dst as *mut u8, src as *u8, n as u64);
 }
 
+/**
+ * Copies data from one location to another
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may overlap.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "64", not(stage0))]
 pub unsafe fn copy_memory<T>(dst: *mut T, src: *const T, count: uint) {
@@ -135,6 +141,13 @@ pub unsafe fn copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: u
     memmove32(dst as *mut u8, src as *u8, n as u32);
 }
 
+/**
+ * Copies data from one location to another. This uses memcpy instead of memmove
+ * to take advantage of the knowledge that the memory does not overlap.
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may overlap.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "32", not(stage0))]
 pub unsafe fn copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: uint) {
@@ -150,6 +163,13 @@ pub unsafe fn copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: u
     memmove64(dst as *mut u8, src as *u8, n as u64);
 }
 
+/**
+ * Copies data from one location to another. This uses memcpy instead of memmove
+ * to take advantage of the knowledge that the memory does not overlap.
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may overlap.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "64", not(stage0))]
 pub unsafe fn copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: uint) {
@@ -164,6 +184,10 @@ pub unsafe fn set_memory<T>(dst: *mut T, c: int, count: uint) {
     libc_::memset(dst as *mut c_void, c as libc::c_int, n as size_t);
 }
 
+/**
+ * Invokes memset on the specified pointer, setting `count` bytes of memory
+ * starting at `dst` to `c`.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "32", not(stage0))]
 pub unsafe fn set_memory<T>(dst: *mut T, c: u8, count: uint) {
@@ -171,6 +195,10 @@ pub unsafe fn set_memory<T>(dst: *mut T, c: u8, count: uint) {
     memset32(dst, c, count as u32);
 }
 
+/**
+ * Invokes memset on the specified pointer, setting `count` bytes of memory
+ * starting at `dst` to `c`.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "64", not(stage0))]
 pub unsafe fn set_memory<T>(dst: *mut T, c: u8, count: uint) {
@@ -268,6 +296,7 @@ pub unsafe fn array_each<T>(arr: **T, cb: &fn(*T)) {
     array_each_with_len(arr, len, cb);
 }
 
+#[allow(missing_doc)]
 pub trait Ptr<T> {
     fn is_null(&const self) -> bool;
     fn is_not_null(&const self) -> bool;