Re: When is the best phase to generate javadocs?
Cool - I did not notice that in the preferences - thanks! Cheers, Eric On 2011-08-09 7:31 AM, Jeff Jensen wrote: Using m2eclipse and turning on its feature to automatically download dependency source and JavaDoc, it will automatically configure what you seek... :-) On Tue, Aug 9, 2011 at 9:18 AM, Eric Kolotyluk eric.koloty...@gmail.com mailto:eric.koloty...@gmail.com wrote: Yes exactly! I do have my Eclipse setup to display the javadoc when I hover my cursor over a class name or method name - I have been doing that for years. It is great! However, this new project I have built is the first time anyone on my team has actually written any overview and package comments. In the past we have relied too much (IMHO) on external documentation that is not as easy to find or access. I am trying develop a new culture where we keep the documentation closer to the source code where people work routinely. Some day I need to find some better tools for creating HTML that just the Eclipse HTML editors. I am very good at writing raw HTML, but my productivity is not very good doing things in such a manual way. Eventually I want to learn how better access the javadoc some people deploy with their Maven artifacts as it is still the case I import something from Maven, but cannot see the javadocs from Eclipse, yet I know they are in the distribution. Cheers, Eric On Tue, Aug 9, 2011 at 6:47 AM, Mark H. Wood mw...@iupui.edu mailto:mw...@iupui.edu wrote: Yes, you *could* rely on your IDE to show you the Javadoc *for the class or method you're currently focused on*. But then you'd miss seeing that you forgot to write the overview, you forgot to write most of the package comments, or that 80% of your classes and methods have either no topic sentence, a useless one, or one that is bizarrely formatted and unreadable. Or the amount of material that doesn't really say anything which would help someone not already intimately familiar with the code. Documentation should be generated and reviewed regularly. -- Mark H. Wood, Lead System Programmer mw...@iupui.edu Asking whether markets are efficient is like asking whether people are smart. - To unsubscribe, e-mail: users-unsubscr...@maven.apache.org For additional commands, e-mail: users-h...@maven.apache.org
Re: When is the best phase to generate javadocs?
Yes, you *could* rely on your IDE to show you the Javadoc *for the class or method you're currently focused on*. But then you'd miss seeing that you forgot to write the overview, you forgot to write most of the package comments, or that 80% of your classes and methods have either no topic sentence, a useless one, or one that is bizarrely formatted and unreadable. Or the amount of material that doesn't really say anything which would help someone not already intimately familiar with the code. Documentation should be generated and reviewed regularly. -- Mark H. Wood, Lead System Programmer mw...@iupui.edu Asking whether markets are efficient is like asking whether people are smart. pgptFSx7Kd4SD.pgp Description: PGP signature
Re: When is the best phase to generate javadocs?
Yes exactly! I do have my Eclipse setup to display the javadoc when I hover my cursor over a class name or method name - I have been doing that for years. It is great! However, this new project I have built is the first time anyone on my team has actually written any overview and package comments. In the past we have relied too much (IMHO) on external documentation that is not as easy to find or access. I am trying develop a new culture where we keep the documentation closer to the source code where people work routinely. Some day I need to find some better tools for creating HTML that just the Eclipse HTML editors. I am very good at writing raw HTML, but my productivity is not very good doing things in such a manual way. Eventually I want to learn how better access the javadoc some people deploy with their Maven artifacts as it is still the case I import something from Maven, but cannot see the javadocs from Eclipse, yet I know they are in the distribution. Cheers, Eric On Tue, Aug 9, 2011 at 6:47 AM, Mark H. Wood mw...@iupui.edu wrote: Yes, you *could* rely on your IDE to show you the Javadoc *for the class or method you're currently focused on*. But then you'd miss seeing that you forgot to write the overview, you forgot to write most of the package comments, or that 80% of your classes and methods have either no topic sentence, a useless one, or one that is bizarrely formatted and unreadable. Or the amount of material that doesn't really say anything which would help someone not already intimately familiar with the code. Documentation should be generated and reviewed regularly. -- Mark H. Wood, Lead System Programmer mw...@iupui.edu Asking whether markets are efficient is like asking whether people are smart.
Re: When is the best phase to generate javadocs?
No, I don't miss that... Again, properly configuring the IDE will give you all that as well. For example, turn on the setting to flag missing or malformed JavaDoc as warning or even error if your group takes it very seriously. Well, if I didn't have a more advanced IDE, I would miss that... ;-) Absolutely, docs should be generated and reviewed regularly along with the other reports from the nightly build (static analysis reports should be reviewed more frequently). Running JavaDoc every hour wouldn't have ever benefited my projects, but YMMV! A nightly build with JavaDoc, JXR, multiple static analysis reports (and smaller but important rule sets that will fail the build) are one of the first things I setup on my projects (as a consultant, I regularly do them). As well as using them real-time with IDE plugins. On Tue, Aug 9, 2011 at 8:47 AM, Mark H. Wood mw...@iupui.edu wrote: Yes, you *could* rely on your IDE to show you the Javadoc *for the class or method you're currently focused on*. But then you'd miss seeing that you forgot to write the overview, you forgot to write most of the package comments, or that 80% of your classes and methods have either no topic sentence, a useless one, or one that is bizarrely formatted and unreadable. Or the amount of material that doesn't really say anything which would help someone not already intimately familiar with the code. Documentation should be generated and reviewed regularly. -- Mark H. Wood, Lead System Programmer mw...@iupui.edu Asking whether markets are efficient is like asking whether people are smart.
Re: When is the best phase to generate javadocs?
Using m2eclipse and turning on its feature to automatically download dependency source and JavaDoc, it will automatically configure what you seek... :-) On Tue, Aug 9, 2011 at 9:18 AM, Eric Kolotyluk eric.koloty...@gmail.comwrote: Yes exactly! I do have my Eclipse setup to display the javadoc when I hover my cursor over a class name or method name - I have been doing that for years. It is great! However, this new project I have built is the first time anyone on my team has actually written any overview and package comments. In the past we have relied too much (IMHO) on external documentation that is not as easy to find or access. I am trying develop a new culture where we keep the documentation closer to the source code where people work routinely. Some day I need to find some better tools for creating HTML that just the Eclipse HTML editors. I am very good at writing raw HTML, but my productivity is not very good doing things in such a manual way. Eventually I want to learn how better access the javadoc some people deploy with their Maven artifacts as it is still the case I import something from Maven, but cannot see the javadocs from Eclipse, yet I know they are in the distribution. Cheers, Eric On Tue, Aug 9, 2011 at 6:47 AM, Mark H. Wood mw...@iupui.edu wrote: Yes, you *could* rely on your IDE to show you the Javadoc *for the class or method you're currently focused on*. But then you'd miss seeing that you forgot to write the overview, you forgot to write most of the package comments, or that 80% of your classes and methods have either no topic sentence, a useless one, or one that is bizarrely formatted and unreadable. Or the amount of material that doesn't really say anything which would help someone not already intimately familiar with the code. Documentation should be generated and reviewed regularly. -- Mark H. Wood, Lead System Programmer mw...@iupui.edu Asking whether markets are efficient is like asking whether people are smart.
When is the best phase to generate javadocs?
I was generating javadocs with the maven-javadoc-plugin in the package phase, but ran into problems because other modules had not been through the install phase yet. To get around the problem I changed it to the deploy phase, but I'm not sure if this is the best place to do it. How do most people handle their javadoc generation in Maven? Is there some best practices documented about this? Cheers, Eric - To unsubscribe, e-mail: users-unsubscr...@maven.apache.org For additional commands, e-mail: users-h...@maven.apache.org
Re: When is the best phase to generate javadocs?
On Tue, Aug 9, 2011 at 10:02 AM, Eric Kolotyluk eric.koloty...@gmail.com wrote: I was generating javadocs with the maven-javadoc-plugin in the package phase, but ran into problems because other modules had not been through the install phase yet. To get around the problem I changed it to the deploy phase, but I'm not sure if this is the best place to do it. How do most people handle their javadoc generation in Maven? Is there some best practices documented about this? I let the release process handle this for me as there is not much value in javadocs for SNAPSHOTS, you want the source instead. - To unsubscribe, e-mail: users-unsubscr...@maven.apache.org For additional commands, e-mail: users-h...@maven.apache.org
Re: When is the best phase to generate javadocs?
Normally I would agree with that, but this is an early stage of development and the javadocs are changing frequently, and I'm putting more stuff in them that would normally be documented elsewhere. Thanks for the advice though, I'll try to study the release process a little more to see if I'm missing something and trying to do more work than I need to. Cheers, Eric On 2011-08-08 5:40 PM, Barrie Treloar wrote: On Tue, Aug 9, 2011 at 10:02 AM, Eric Kolotyluk eric.koloty...@gmail.com wrote: I was generating javadocs with the maven-javadoc-plugin in the package phase, but ran into problems because other modules had not been through the install phase yet. To get around the problem I changed it to the deploy phase, but I'm not sure if this is the best place to do it. How do most people handle their javadoc generation in Maven? Is there some best practices documented about this? I let the release process handle this for me as there is not much value in javadocs for SNAPSHOTS, you want the source instead. - To unsubscribe, e-mail: users-unsubscr...@maven.apache.org For additional commands, e-mail: users-h...@maven.apache.org - To unsubscribe, e-mail: users-unsubscr...@maven.apache.org For additional commands, e-mail: users-h...@maven.apache.org
Re: When is the best phase to generate javadocs?
I prefer to gen JavaDoc in the nightly site gen run, from the parent. Avoids the problem you mentioned. You could run a site gen multiple times per day, if it's not a long duration. These days, IDEs such as Eclipse display JavaDoc pulled directly from source, so you could avoid a JavaDoc gen entirely if you configure the IDE correctly. And, as your code base grows, the build time will slow - so not the time to gen JavaDoc at any phase of the normal build. On Mon, Aug 8, 2011 at 10:53 PM, Eric Kolotyluk eric.koloty...@gmail.comwrote: Normally I would agree with that, but this is an early stage of development and the javadocs are changing frequently, and I'm putting more stuff in them that would normally be documented elsewhere. Thanks for the advice though, I'll try to study the release process a little more to see if I'm missing something and trying to do more work than I need to. Cheers, Eric On 2011-08-08 5:40 PM, Barrie Treloar wrote: On Tue, Aug 9, 2011 at 10:02 AM, Eric Kolotyluk eric.koloty...@gmail.com wrote: I was generating javadocs with the maven-javadoc-plugin in the package phase, but ran into problems because other modules had not been through the install phase yet. To get around the problem I changed it to the deploy phase, but I'm not sure if this is the best place to do it. How do most people handle their javadoc generation in Maven? Is there some best practices documented about this? I let the release process handle this for me as there is not much value in javadocs for SNAPSHOTS, you want the source instead. --**--**- To unsubscribe, e-mail: users-unsubscribe@maven.**apache.orgusers-unsubscr...@maven.apache.org For additional commands, e-mail: users-h...@maven.apache.org --**--**- To unsubscribe, e-mail: users-unsubscribe@maven.**apache.orgusers-unsubscr...@maven.apache.org For additional commands, e-mail: users-h...@maven.apache.org
Re: When is the best phase to generate javadocs?
On Tue, Aug 9, 2011 at 2:00 PM, Jeff Jensen jeffjen...@upstairstechnology.com wrote: I prefer to gen JavaDoc in the nightly site gen run, from the parent. Avoids the problem you mentioned. You could run a site gen multiple times per day, if it's not a long duration. And we do this too, since there may be other things besides javadoc you want to reference, Think anything in src/main/site. These days, IDEs such as Eclipse display JavaDoc pulled directly from source, so you could avoid a JavaDoc gen entirely if you configure the IDE correctly. This was what I was meaning. And, as your code base grows, the build time will slow - so not the time to gen JavaDoc at any phase of the normal build. +1 to sub 10 minute developer builds http://www.google.com/search?q=sub+10+minute+developer+builds e.g. http://jamesshore.com/Agile-Book/ten_minute_build.html - To unsubscribe, e-mail: users-unsubscr...@maven.apache.org For additional commands, e-mail: users-h...@maven.apache.org
