You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@directory.apache.org by Felix Knecht <fe...@otego.com> on 2010/06/07 10:04:07 UTC
Javadocs fixing/creating
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hi dev
Are you aware of
http://maven.apache.org/plugins/maven-javadoc-plugin/fix-mojo.html?
This will create (depending on the properties you set on CLI) missing
javadocs on in the source files. Properties can also be configured in
each project pom.xml.
I suggest to fix at least ClassComments for now. Resulting is shown in
sample below.
WDYT?
Following will e.g. fix the ClassComment and add a missing @author tag:
mvn javadoc:fix -DdefaultAuthor="<a
href=\"mailto:dev@directory.apache.org\">Apache Directory Project</a>"
- -DfixTags="author" -DfixFieldComment=false -DfixMethodComment=false
-Dforce
like
Index:
ldap-client-api/src/main/java/org/apache/directory/ldap/client/api/LdapAsyncConnection.java
===================================================================
- ---
ldap-client-api/src/main/java/org/apache/directory/ldap/client/api/LdapAsyncConnection.java
(revision 952127)
+++
ldap-client-api/src/main/java/org/apache/directory/ldap/client/api/LdapAsyncConnection.java
(working copy)
@@ -25,6 +25,11 @@
import org.apache.directory.shared.ldap.name.DN;
+/**
+ * <p>LdapAsyncConnection interface.</p>
+ *
+ * @author <a href="mailto:dev@directory.apache.org">Apache Directory
Project</a>
+ */
public interface LdapAsyncConnection extends LdapConnection
{
@@ -184,4 +189,4 @@
* @return
*/
LdapConnectionConfig getConfig();
- -}
\ No newline at end of file
+}
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.15 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkwMp/cACgkQ2lZVCB08qHHBOQCg2C8KdvrQYnQBNcokhOkOh3Rx
fcIAmwY4a0Jlu/72qsk9WGr5usn6uh3P
=HbLW
-----END PGP SIGNATURE-----
Re: Javadocs fixing/creating
Posted by Felix Knecht <fe...@apache.org>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On 06/07/10 10:20, Pierre-Arnaud Marcelot wrote:
> Hi Felix,
>
> Sounds very interesting to have this done automatically.
>
> May I suggest that we add something like "TODO: Review and document me!" (or something equivalent) in the template, to make sure the classes and interfaces get well documented some day.
> It would be easier to find javadocs with missing information.
I agree, but I haven't found yet where to override this to set a TODO ...
>
> Regards,
> Pierre-Arnaud
>
> On 7 juin 2010, at 10:04, Felix Knecht wrote:
>
> Hi dev
>
> Are you aware of
> http://maven.apache.org/plugins/maven-javadoc-plugin/fix-mojo.html?
>
> This will create (depending on the properties you set on CLI) missing
> javadocs on in the source files. Properties can also be configured in
> each project pom.xml.
>
> I suggest to fix at least ClassComments for now. Resulting is shown in
> sample below.
>
> WDYT?
>
> Following will e.g. fix the ClassComment and add a missing @author tag:
>
> mvn javadoc:fix -DdefaultAuthor="<a
> href=\"mailto:dev@directory.apache.org\">Apache Directory Project</a>"
> -DfixTags="author" -DfixFieldComment=false -DfixMethodComment=false
> -Dforce
>
> like
>
> Index:
> ldap-client-api/src/main/java/org/apache/directory/ldap/client/api/LdapAsyncConnection.java
> ===================================================================
> ---
> ldap-client-api/src/main/java/org/apache/directory/ldap/client/api/LdapAsyncConnection.java
> (revision 952127)
> +++
> ldap-client-api/src/main/java/org/apache/directory/ldap/client/api/LdapAsyncConnection.java
> (working copy)
> @@ -25,6 +25,11 @@
> import org.apache.directory.shared.ldap.name.DN;
>
>
> +/**
> + * <p>LdapAsyncConnection interface.</p>
> + *
> + * @author <a href="mailto:dev@directory.apache.org">Apache Directory
> Project</a>
> + */
> public interface LdapAsyncConnection extends LdapConnection
> {
>
> @@ -184,4 +189,4 @@
> * @return
> */
> LdapConnectionConfig getConfig();
> -}
> \ No newline at end of file
> +}
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.15 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkwMrPkACgkQ2lZVCB08qHFcBwCfW9AROWbfgBe0GfOyOezNu4Ha
vesAoKunRvq7R3Fy5PdBtFwHH+bjUAD9
=Zm6G
-----END PGP SIGNATURE-----
Re: Javadocs fixing/creating
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
Hi Felix,
Sounds very interesting to have this done automatically.
May I suggest that we add something like "TODO: Review and document me!" (or something equivalent) in the template, to make sure the classes and interfaces get well documented some day.
It would be easier to find javadocs with missing information.
Regards,
Pierre-Arnaud
On 7 juin 2010, at 10:04, Felix Knecht wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi dev
>
> Are you aware of
> http://maven.apache.org/plugins/maven-javadoc-plugin/fix-mojo.html?
>
> This will create (depending on the properties you set on CLI) missing
> javadocs on in the source files. Properties can also be configured in
> each project pom.xml.
>
> I suggest to fix at least ClassComments for now. Resulting is shown in
> sample below.
>
> WDYT?
>
> Following will e.g. fix the ClassComment and add a missing @author tag:
>
> mvn javadoc:fix -DdefaultAuthor="<a
> href=\"mailto:dev@directory.apache.org\">Apache Directory Project</a>"
> - -DfixTags="author" -DfixFieldComment=false -DfixMethodComment=false
> -Dforce
>
> like
>
> Index:
> ldap-client-api/src/main/java/org/apache/directory/ldap/client/api/LdapAsyncConnection.java
> ===================================================================
> - ---
> ldap-client-api/src/main/java/org/apache/directory/ldap/client/api/LdapAsyncConnection.java
> (revision 952127)
> +++
> ldap-client-api/src/main/java/org/apache/directory/ldap/client/api/LdapAsyncConnection.java
> (working copy)
> @@ -25,6 +25,11 @@
> import org.apache.directory.shared.ldap.name.DN;
>
>
> +/**
> + * <p>LdapAsyncConnection interface.</p>
> + *
> + * @author <a href="mailto:dev@directory.apache.org">Apache Directory
> Project</a>
> + */
> public interface LdapAsyncConnection extends LdapConnection
> {
>
> @@ -184,4 +189,4 @@
> * @return
> */
> LdapConnectionConfig getConfig();
> - -}
> \ No newline at end of file
> +}
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.15 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAkwMp/cACgkQ2lZVCB08qHHBOQCg2C8KdvrQYnQBNcokhOkOh3Rx
> fcIAmwY4a0Jlu/72qsk9WGr5usn6uh3P
> =HbLW
> -----END PGP SIGNATURE-----
Re: Javadocs fixing/creating
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 6/7/10 11:00 AM, Felix Knecht wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
>> Yes, sure, we can use this guy. But I would rather expect that we
>> manually add the missing Javadoc, assuming that the generated reports
>> tell us which ones are missing.
>>
>> My fear is that we consider a missing header as a non issue, as the mavn
>> plugin will 'fix it'...
>>
>> Also it may create some burden as you will have some more file to commit.
>>
> We can add just the configuration to the pom.xml/build section like
> <plugin>
> <groupId>org.apache.maven.plugins</groupId>
> <artifactId>maven-javadoc-plugin</artifactId>
> <configuration>
> <defaultAuthor><a
> href="mailto:dev@directory.apache.org\">Apache Directory
> Project</a></defaultAuthor>
> <fixTags>author,param,return,throws</fixTags>
> <level>private</level>
> <force>true</force>
> </configuration>
> </plugin>
>
> This will not be executed when running a simple mvn clean install. One
> still will need to run mvn javadoc:fix from CLI, but you don't need to
> have all the relevant properties to set.
>
+1 for this.
--
Regards,
Cordialement,
Emmanuel Lécharny
www.nextury.com
Re: Javadocs fixing/creating
Posted by Felix Knecht <fe...@apache.org>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
> Yes, sure, we can use this guy. But I would rather expect that we
> manually add the missing Javadoc, assuming that the generated reports
> tell us which ones are missing.
>
> My fear is that we consider a missing header as a non issue, as the mavn
> plugin will 'fix it'...
>
> Also it may create some burden as you will have some more file to commit.
We can add just the configuration to the pom.xml/build section like
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<defaultAuthor><a
href="mailto:dev@directory.apache.org\">Apache Directory
Project</a></defaultAuthor>
<fixTags>author,param,return,throws</fixTags>
<level>private</level>
<force>true</force>
</configuration>
</plugin>
This will not be executed when running a simple mvn clean install. One
still will need to run mvn javadoc:fix from CLI, but you don't need to
have all the relevant properties to set.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.15 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkwMtTIACgkQ2lZVCB08qHEZkgCg8HbdNR6iQwo0ExWs5FDimsCC
QYAAn1g0TAvQ35LkQY1iAo11wPDrd78N
=d0C9
-----END PGP SIGNATURE-----
Re: Javadocs fixing/creating
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 6/7/10 10:04 AM, Felix Knecht wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi dev
>
> Are you aware of
> http://maven.apache.org/plugins/maven-javadoc-plugin/fix-mojo.html?
>
> This will create (depending on the properties you set on CLI) missing
> javadocs on in the source files. Properties can also be configured in
> each project pom.xml.
>
> I suggest to fix at least ClassComments for now. Resulting is shown in
> sample below.
>
> WDYT?
>
Yes, sure, we can use this guy. But I would rather expect that we
manually add the missing Javadoc, assuming that the generated reports
tell us which ones are missing.
My fear is that we consider a missing header as a non issue, as the mavn
plugin will 'fix it'...
Also it may create some burden as you will have some more file to commit.
May be we can run it once, but we then should add a @Todo Javadoc
generated by Maven on the header.-----END PGP SIGNATURE-----
>
--
Regards,
Cordialement,
Emmanuel Lécharny
www.nextury.com