This issue has been tracked via SCR-1509: "help framework should allow @see and @link usage within jtags" (see this link).

It was agreed in the DP-DOC-WG telecon on 29 June 2005 that there can be references from the Users Reference Manual (URM) to developer documentation such as javadoc, and such references can be facilitated using jtags (jtags enable user documentation to be embedded into source code).

What had not been clarified in that telecon, and the main reason why SCR-1509 remains open, is whether developer documentation can reference a section of a user document such as the Users Manual or the URM. HS preferred that user documentation is not referenced by developer documentation, but this was not agreed by SG or RH. RH pointed out that it might be difficult to reference user documentation from javadoc if the user documentation is automatically generated by an XSLT processor. Such a processor splits a document in individual files for each chapter and section. The files are named using the chapter and section numbers. When the author of a document re-shuffles the sections or chapters there is no way to update the links in the javadoc. RH proposed that references from javadoc to user documentation are made only to the document as a whole, not to individual sections. There might however be a possibility to use the ID attribute in a chapter xml tag. This is because if a chapter has an ID attribute, this ID will be used as the filename.

It was agreed that referencing of user documentation from javadoc would only be to the entry point of the user document in question. For example, for the User's Manual, the entry file in HTML is the file um.html . For the URM, it is the file urm.html .