Links and search do not make sense and are not working across projects

Migrated issue

Reported by: rfay

Problem/Motivation

The API module allows you to have multiple Projects and Branches. However, links and searching are not working in sensible/useful ways across projects.

Scenario: You are setting up an API site for Drupal Core, Views, Panels, CCK, and FileField documentation. Each one is set up as its own Project, and within each Project, you have branches for 6.x/7.x (core), or 6.x-1.x, 6.x-2.x, 7.x-1.x, etc. (contrib).

Problem 1: Links are not made across projects. So if you're on a Drupal Core function page, you'll see all function calls there turned into links to other Drupal Core functions. But if you're in Views, you won't see links to the Drupal Core functions; FileField won't link to CCK functions, etc. Same for topics, files, etc.

Problem 2: The search blocks are currently set up to search across projects within a branch -- meaning that you can search "6.x", and any branch labeled as "6.x" in any project will be searched. And you can search "6.x-2.x", and any branch labeled as "6.x-2.x" in any project will be searched. However, this doesn't really make sense, because there is not really any correlation between CCK 6.x-2.x, FileField 6.x-2.x, and Views 6.x-2.x, for instance. This also is confusing, because all of the other API project navigation and breadcrumbs stay within a certain project and then within a certain branch.

Proposed resolution

(rejected) PROPOSED RESOLUTION #1:

One possible resolution is what psynaptic does on drupalcontrib.org: put everything into one big project rather than having separate projects for Core and each Contrib module. The advantage is that neither of the two problems above applies. The disadvantage is that you have to pick one particular branch for each module (e.g., you can't have both 6.x-1.x and 6.x-2.x probably).

We do not want to enforce this as the only way to set up an API site, so this proposed resolution is not what we want to do.

PROPOSED RESOLUTION #2:

A second possible resolution is to allow the project/branch setup in the scenario above (in the Problem section), but revise the way links and searching are done. Here are the changes to be made for this issue:

a) Revise the Project and Branch setup in the API module:
- Projects will be in their own table. Each project will have a machine name (e.g., drupal, views), a title (e.g., Drupal Core, Views), and a type (e.g., core, module).
- Each branch will be associated with a project, and will include fields for Core Compatibility (6.x, 7.x, 8.x, ...) as well as the specific branch (6.x-1.x, 6.x-2.x, ...). You will be able to mark a branch as "preferred", with the assumption that there should only be one "preferred" branch for each project within each core compatibility (e.g., Views 6.x-2.x and 7.x-3.x would be "preferred" within the Views project, but you could also display the 6.x-1.x branch on the site).

b) When making links in code and documentation:
- If we're in a "core" project's branch, it should work as it does now (try to find a match in this branch, and if there isn't one, check the PHP reference branches for a match).
- If we're in a module/theme project's branch, it should work as it does now, but if a match isn't found for a particular function within that branch, it should find the "core" branch with the same core compatibility, and look for matches there too. If that still yields no match, then we can look in other projects within the same core compatibility, with preference given to the "preferred" branches.

c) For reference pages ("functions that call this" and similar pages), we would need a somewhat related logic:
- When you click the link, it should give you just the reference links for the current branch.
- There should be a tab for references from other projects (within the same core compatibility, and probably limited to "preferred" branches?). This would probably need to be paginated! (I don't think the references pages are currently paginated.) Probably on the main function page there should be links to both the functions within this project/branch that call it, and to the functions from other branches. Note: This is killed in favor of having an advanced search.

d) Search... We probably need to have some search options:
1. Search within a single core branch only.
2. Search within a single branch of a different project only.
3. Search across preferred branches within a single core compatibility.

Remaining tasks

From the proposed resolution, (a) has been done. The rest remains to be implemented.

For search across different projects and branches, there is a separate issue:
#1788240 (closed)

User interface changes

Links and searching would behave differently for multiple-project sites than their current behavior. API module administration screens would be different because branches and projects are separate.

API changes

Search and linking would behave differently from their current behavior. Branches and projects would have a different database structure.

Original report by rfay

In the top of ajax_example.module there is an @Link:

 * @link ajax AJAX Framework documentation @endlink and at the

This should point to the ajax group in ajax.inc:

/**
 * @defgroup ajax AJAX framework
 * @{

But as you can see at http://api.drupal.org/api/examples/ajax_example--ajax_example.module/group/ajax_examples/7, it doesn't turn into a link.

So unless I'm just missing something stupid, something is broken on group linking. Correct me if I've done something stupid.