API Tooling is not a new feature. It came out of incubation in 3.4 and has been explained nicely at developerworks and eclipse wiki. What I would cover below is how to do it for existing projects and the strategy to continue with it.
- Setting up API Tooling Note: API Tooling works only for plug-in projects. It can not be used for Java, Feature and Update site projects API Tooling for a project is setup by attaching an API Nature to the project. When completed you will be prompted to make a baseline.
- Baselining A baseline is a snapshot (set) of plug-ins. The AP Tooling expects not just the plug-ins you exported from your workspace, but also the dependent plug-ins. If the complete set is not available, the Compare with baseline will not work. If your plug-ins makes a product, then export the product configuration and point to it as baseline. If its a set of features then just exporting them will not be enough. The dependent plug-ins are required too. You pull them all by modifying your ant build script. I don't know any shortcut/simple way of achieving this.
- Comparing with baselines API Tooling is a new view available with3.5. It can be quick accessed through context menu (Compare with > API Baseline...) on a project, a folder, a package or any java resource in package explorer. Compare Baseline compares the selected resource with the selected baseline. Any changes are reported in the API. Note that you can compare two baseline with each other here. Its the code against the selected baseline.
- Going ahead Having a baseline on each minor version will be a overkill. I would have one for each major release and one for each milestone during the development cycle. API Tooling can also be integrated in the PDE Build. Look for Eclipse help contents PDE Guide > Reference > API Tools Ant Tasks. For a quick list type apitooling in build.xml and press Ctrl + Space (content assist). API Tooling view allows exporting the results as XML or HTML. Same can be automated using ant tasks.