+\subsection{Attributes in Documentation Comments}
+
+To reduce clutter due to annotations, nesC allows attributes placed
+within a documentation comment before a function signature to apply to
+that function's parameters and return type.
+
+Specifically, a comment of the form
+\begin{verbatim}
+/**
+ ... @param '<parameter-declaration>'
+*/
+\end{verbatim}
+before a function declaration or definition will replace the
+correspondingly named parameter with {\em parameter-declaration}. It
+is a compile-time error if the type doesn't match, i.e. the two
+declarations must only differ in their attributes (on the parameter or
+in its type). It is also a compile-time error if {\em
+ parameter-declaration} does not name a parameter of the function.
+
+For instance:
+\begin{verbatim}
+ struct @count { int size; };
+ /** f is an exiciting function.
+ @param 'int *@count(n) x' x is an array of n ints.
+ @param n n is size of array x.
+ */
+ void f(int *x, int n);
+\end{verbatim}
+is the same as
+\begin{verbatim}
+ struct @count { int size; };
+ void f(int *@count(n) x, int n);
+\end{verbatim}
+
+Macros can be used in the documentation comment, so the above could
+also be written:
+\begin{verbatim}
+ #define COUNT(expr) @count(expr)
+ struct @count { int size; };
+ /** f is an exiciting function.
+ @param 'int *COUNT(n) x' x is an array of n ints.
+ @param n n is the size of array x.
+ */
+ void f(int *x, int n);
+\end{verbatim}
+
+For return types, a comment of the form
+\begin{verbatim}
+/**
+ ... @return '<type-name>'
+*/
+\end{verbatim}
+before a function declaration or definition will replace the
+function's return type with {\em type-name}. It
+is a compile-time error if the type doesn't match, i.e. the two
+types must only differ in their attributes.
+
+For instance:
+\begin{verbatim}
+ struct @count { int size; };
+ /** g gives us some data.
+ @param n n is the size of the returned data.
+ @return 'int *@count(n)' the returned data is n ints.
+ */
+ int *g(int n);
+\end{verbatim}
+is the same as
+\begin{verbatim}
+ struct @count { int size; };
+ int *@count(n) g(int n);
+\end{verbatim}
+
+As with parameters, the type in \code{@return} may use macros.
+