title: How to properly document S4 class slots using Roxygen2?
body: <p>For documenting classes with roxygen(2), specifying a title and description/details appears to be the same as for functions, methods, data, etc. However, slots and inheritance are their own sort of animal. What is the best practice -- current or planned -- for documenting S4 classes in roxygen2?</p>
  
  <p>Due Diligence:</p>
  
  <p>I found mention of an <code>@slot</code> tag in early descriptions of roxygen. 
  <a href="http://lists.r-forge.r-project.org/pipermail/roxygen-devel/2008-November/000009.html" rel="noreferrer">A 2008 R-forge mailing list post</a> 
  seems to indicate that this is dead, 
  and there is no support for <code>@slot</code> in roxygen:</p>
  
  <p>Is this true of roxygen2? The previously-mentioned post suggests a user should instead make their own itemized list with LaTeX markup. E.g. a new S4 class that extends the <code>"character"</code> class would be coded and documented like this:</p>
  
  <pre><code>#' The title for my S4 class that extends \code{"character"} class.
  #'
  #' Some details about this class and my plans for it in the body.
  #'
  #' \describe{
  #'    \item{myslot1}{A logical keeping track of something.}
  #'
  #'    \item{myslot2}{An integer specifying something else.}
  #' 
  #'    \item{myslot3}{A data.frame holding some data.}
  #'  }
  #' @name mynewclass-class
  #' @rdname mynewclass-class
  #' @exportClass mynewclass
  setClass("mynewclass",
      representation(myslot1="logical",
          myslot2="integer",
          myslot3="data.frame"),
      contains = "character"
  )
  </code></pre>
  
  <p>However, although this works, this <code>\describe</code> , <code>\item</code> approach for documenting the slots seems inconsistent with the rest of roxygen(2), in that there are no <code>@</code>-delimited tags and slots could go undocumented with no objection from <code>roxygenize()</code>. It also says nothing about a consistent way to document inheritance of the class being defined. I imagine dependency still generally works fine (if a particular slot requires a non-base class from another package) using the <code>@import</code> tag. </p>
  
  <p>So, to summarize, what is the current best-practice for roxygen(2) slots?</p>
  
  <p>There seem to be three options to consider at the moment:</p>
  
  <blockquote>
    <ul>
    <li>A -- Itemized list (as example above).</li>
    <li>B -- <code>@slot</code> ... but with extra tags/implementation I missed. I was    unable to get @slot to work with roxygen / roxygen2 in versions where 
    it was included as a replacement for the itemized list in the example 
    above. Again, the example above does work with roxygen(2). </li>
    <li>C -- Some alternative tag for specifying slots, like <code>@param</code>, that    would accomplish the same thing.</li>
    </ul>
  </blockquote>
  
  <p>I'm borrowing/extending this question from a post I made to the <code>roxygen2</code> development page on <a href="https://github.com/klutometis/roxygen/issues/34" rel="noreferrer">github</a>.</p>