2 Replies Latest reply on Jan 22, 2010 11:32 AM by dmlloyd

    Aggregated Microcontainer JavaDoc

    thomas.diesler

      I started a project that aims to generate comprehensive javadoc for the public Microcontainer API/SPI

       

      https://jira.jboss.org/jira/browse/JBMICROCONT-442

       

      On this topic Jason says


      All of our code, especially SPI or API classes must have javadoc which explains in detail the following things:

      1) How the module is supposed to be used (and how it is actually used if known)
      2) The intended behaviour, and any aspect of it that is known to be broken or a hack (so that someone can differentiate between a design problem and just an unimplemented section that needs to be fixed)
      3) Critical preconditions (e.g. "this class expects that the same vfs handle instance be reused during a redeploy")
      4) Thread-access design (e.g. "this class is thread-safe and can be accessed from multiple threads", "this class is not thread-safe, and all callers must use a shared lock to access", "this class is intended to have an instance-per-thread")

       


      New snapshots of the docs are generated by this Hudson Job. The generated JavaDocs are available here

       

      Currently, this project aggregates

       

          <dependencySet>
            <outputDirectory>/</outputDirectory>
            <useStrictFiltering>true</useStrictFiltering>
            <includes>
              <include>*:jboss-classloader:jar:sources</include>
              <include>*:jboss-classloading:jar:sources</include>
              <include>*:jboss-classloading-vfs:jar:sources</include>
              <include>*:jboss-dependency:jar:sources</include>
              <include>*:jboss-deployers-client-spi:jar:sources</include>
              <include>*:jboss-deployers-core-spi:jar:sources</include>
              <include>*:jboss-deployers-spi:jar:sources</include>
              <include>*:jboss-deployers-structure-spi:jar:sources</include>
              <include>*:jboss-deployers-vfs:jar:sources</include>
              <include>*:jboss-deployers-vfs-spi:jar:sources</include>
              <include>*:jboss-kernel:jar:sources</include>
            </includes>
            <unpack>true</unpack>
          </dependencySet>
      
      

       

      and excludes these packages

       

      <excludePackageNames>*.internal:*.integration</excludePackageNames>
      
      

       

      At this stage, I am looking for the correct set of modules that need to be aggregated and the package name patterns are not part of public API/SPI.

        • 1. Re: Aggregated Microcontainer JavaDoc
          alesj

          At this stage, I am looking for the correct set of modules that need to be aggregated and the package name patterns are not part of public API/SPI.

          Any module that is used by AS should be definitely aggregated.

          But there are some optional, which have not been added to AS by default: Kernel's Weld-int, Guice-int and Spring-int.

           

          For the packages we usually (until your OSGi Facade re-packaging ) use org.jboss.<module>.spi|api|plugins.

          spi = dev code

          api = user code

          plugins = impl detail

          • 2. Re: Aggregated Microcontainer JavaDoc
            dmlloyd

            alesj wrote:

             

            Any module that is used by AS should be definitely aggregated.

            But there are some optional, which have not been added to AS by default: Kernel's Weld-int, Guice-int and Spring-int.

            It might not matter so much, including optional stuff, if you separate the packages into groups by original module.  Maybe the maven javadoc aggregator already does this?