Package comments and excluded files

Question

I have an ant target to generate javadoc for a whole package structure minus one sub-package and one class, plus a few classes from another package:
  <target name="doc">
    <mkdir dir="${build}/docs/api"/>
    <javadoc destdir="${build}/docs/api/"
      use="true"
      windowtitle="Public API">
      <classpath>
        <path refid="3rdparty.jar.path"/>
      </classpath>
      <fileset dir="${build}">
        <include name="com/company/pkg1/**"/>
        <exclude name="com/company/pkg1/util/**"/>
        <exclude name="com/company/pkg1/server/ServiceMBean.java"/>
        <include name="com/company/pkg2/CustomerReport.java"/>
        <include name="com/company/pkg2/DeprecatedReport.java"/>
        <include name="com/company/pkg2/Report.java"/>
        <include name="com/company/pkg2/TagReport.java"/>
      </fileset>
    </javadoc>
  </target>This worked fine until I started including package.html files for package documentation. Running this with package.html in com/company/pkg1 gives the following error:
javadoc: Illegal package name: "C:\abc\def\com\company\pkg1\package.html"
After playing around, I found that if I shift the 3 <include> and <exclude> lines referring to pkg1 out of the <fileset> tag and into a <packageset> tag, then the package comments work. However, then the exclude for the individual java class (ServiceMBean.java) does not work. Likewise, shifting the file exclude back to the fileset tag still does not exclude it.
It seems that I must decide whether to have package comments or the ability to exclude individual files, but not both. Is there any way around this?

Answer 1

Well, it is a known issue. And actually, issue is with DBMS_METADATA, not with DATAPUMP, which simply uses DBMS_METADATA:
SQL> create or replace package
  2  --comment
  3  MyPkg
  4  is
  5  a number;
  6  end;
  7  /
Package created.
SQL> select text from user_source where name = 'MYPKG' order by line;
TEXT
package
--comment
MyPkg
is
a number;
end;
6 rows selected.
SQL> select dbms_metadata.get_ddl('PACKAGE','MYPKG') from dual;
DBMS_METADATA.GET_DDL('PACKAGE','MYPKG')
  CREATE OR REPLACE PACKAGE "SCOTT"."MYPKG"
is
a number;
end;
SQL> You should put comments after package name:
SQL> create or replace package
  2  MyPkg
  3  --comment
  4  is
  5  a number;
  6  end;
  7  /
Package created.
SQL> select dbms_metadata.get_ddl('PACKAGE','MYPKG') from dual;
DBMS_METADATA.GET_DDL('PACKAGE','MYPKG')
  CREATE OR REPLACE PACKAGE "SCOTT"."MYPKG"
--comment
is
a number;
end;
SQL> SY.