Derby
  1. Derby
  2. DERBY-6065

LockTable API link in the documentation is broken

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.9.1.0
    • Fix Version/s: 10.10.1.1
    • Component/s: Documentation
    • Labels:
      None

      Description

      I happened to notice that some of the links in the documentation are broken.

      For example, on http://db.apache.org/derby/docs/10.9/devguide/cdevconcepts50894.html
      the link to LockTable API documentation is broken.

      There are also broken links to the documentation in the wiki, but that's not something we track with JIRA issues, I think. But it would be nice to figure out if we can clean up those links easily. For example, on http://wiki.apache.org/db-derby/LockDebugging there are broken links to the LockTable API documentation, as well as to the SYSCS_DIAG table documentation.

      1. StatementCache.html
        36 kB
        Kim Haase
      2. DERBY-6065-code.diff
        0.9 kB
        Kim Haase
      3. DERBY-6065-2.zip
        8 kB
        Kim Haase
      4. DERBY-6065-2.stat
        0.1 kB
        Kim Haase
      5. DERBY-6065-2.diff
        3 kB
        Kim Haase
      6. DERBY-6065-2.zip
        5 kB
        Kim Haase
      7. DERBY-6065-2.stat
        0.1 kB
        Kim Haase
      8. DERBY-6065-2.diff
        2 kB
        Kim Haase
      9. DERBY-6065.zip
        42 kB
        Kim Haase
      10. DERBY-6065.stat
        0.7 kB
        Kim Haase
      11. DERBY-6065.diff
        70 kB
        Kim Haase

        Activity

        Hide
        Dag H. Wanvik added a comment -

        Looks like these links presume a "dev" location for the latest docs, cf this link:

        http://db.apache.org/derby/docs/dev/devguide/cdevconcepts30291.html

        Right under the "docs" directory there are currently only version directories:

        10.1, 10.2, ..., 10.9. There is no "dev" directory with the latest trunk docs anymore,
        these are now at:

        https://builds.apache.org/job/Derby-docs/lastSuccessfulBuild/artifact/trunk/out/

        {devguide, ... }

        Rather than having to hand edit all the wiki documents referencing the "dev" location, maybe we could
        make "dev" a symlink" the latest released docs, i.e. "10.9"? [Plus a step to update the link in the instructions for publishing a new release docs.. ]

        Or is it important/crucial that the wiki always references the trunk docs?

        Show
        Dag H. Wanvik added a comment - Looks like these links presume a "dev" location for the latest docs, cf this link: http://db.apache.org/derby/docs/dev/devguide/cdevconcepts30291.html Right under the "docs" directory there are currently only version directories: 10.1, 10.2, ..., 10.9. There is no "dev" directory with the latest trunk docs anymore, these are now at: https://builds.apache.org/job/Derby-docs/lastSuccessfulBuild/artifact/trunk/out/ {devguide, ... } Rather than having to hand edit all the wiki documents referencing the "dev" location, maybe we could make "dev" a symlink" the latest released docs, i.e. "10.9"? [Plus a step to update the link in the instructions for publishing a new release docs.. ] Or is it important/crucial that the wiki always references the trunk docs?
        Hide
        Rick Hillegas added a comment -

        I'm puzzled by this problem. When a user guide links to javadoc, it should point at the javadoc for a specific release, namely, the rev level of the user guide. Pointing to the trunk javadoc seems wrong to me. Pointing to the latest release's javadoc seems wrong too.

        It's possible that the move to svnpubsub broke this, but I don't understand how. I looked at the pre-svnpubsub docs on people.apache.org at /www/db.apache.org/content/derby/docs. Next to each release's docs, I see a directory of publishedapi. But that's just the public api javadoc, not the full engine javadoc. So the release-specific javadoc for LockTable has never been included with our release docs. I don't understand how this link ever worked.

        Possible solutions include:

        o Publishing the full engine javadoc with each release.

        o Adding LockTable's javadoc to our public api.

        o Including LockTable's javadoc in the user guide.

        Show
        Rick Hillegas added a comment - I'm puzzled by this problem. When a user guide links to javadoc, it should point at the javadoc for a specific release, namely, the rev level of the user guide. Pointing to the trunk javadoc seems wrong to me. Pointing to the latest release's javadoc seems wrong too. It's possible that the move to svnpubsub broke this, but I don't understand how. I looked at the pre-svnpubsub docs on people.apache.org at /www/db.apache.org/content/derby/docs. Next to each release's docs, I see a directory of publishedapi. But that's just the public api javadoc, not the full engine javadoc. So the release-specific javadoc for LockTable has never been included with our release docs. I don't understand how this link ever worked. Possible solutions include: o Publishing the full engine javadoc with each release. o Adding LockTable's javadoc to our public api. o Including LockTable's javadoc in the user guide.
        Hide
        Kim Haase added a comment -

        The link to the javadoc was put in as part of the fix to DERBY-2845 several years ago.

        The links at the bottom of the Derby documentation page now point to the latest builds of the javadoc rather than the "dev" directory. So the LockTable javadoc is under

        https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/index.html

        So this link will work:

        https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/org/apache/derby/diag/LockTable.html

        These links are likely to keep working if we want to use them, aren't they? In theory we could either link directly to the LockTable page or say "See the documentation for org.apache.derby.diag.LockTable under https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/index.html".

        There are some similarly broken links elsewhere – the JMX documentation in the Admin Guide points to "http://db.apache.org/derby/javadoc/publishedapi/jdbc4/", which no longer works, though it must have worked a year ago. We can't point directly to release-specific API docs from the other documentation, since the link is quite different in the development docs versus the released docs.

        It is probably a lot safer to do what we generally do in the Reference Manual, to say something like "For more information, see the public API javadoc for org.apache.derby.catalog.SequencePreallocator."

        Maybe we should generalize this issue to "Direct API links in the documentation are broken" so we can fix both the Dev Guide link and the Admin Guide ones. Anyone can fix the wiki links as they see fit, I think.

        Show
        Kim Haase added a comment - The link to the javadoc was put in as part of the fix to DERBY-2845 several years ago. The links at the bottom of the Derby documentation page now point to the latest builds of the javadoc rather than the "dev" directory. So the LockTable javadoc is under https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/index.html So this link will work: https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/org/apache/derby/diag/LockTable.html These links are likely to keep working if we want to use them, aren't they? In theory we could either link directly to the LockTable page or say "See the documentation for org.apache.derby.diag.LockTable under https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/index.html ". There are some similarly broken links elsewhere – the JMX documentation in the Admin Guide points to "http://db.apache.org/derby/javadoc/publishedapi/jdbc4/", which no longer works, though it must have worked a year ago. We can't point directly to release-specific API docs from the other documentation, since the link is quite different in the development docs versus the released docs. It is probably a lot safer to do what we generally do in the Reference Manual, to say something like "For more information, see the public API javadoc for org.apache.derby.catalog.SequencePreallocator." Maybe we should generalize this issue to "Direct API links in the documentation are broken" so we can fix both the Dev Guide link and the Admin Guide ones. Anyone can fix the wiki links as they see fit, I think.
        Hide
        Rick Hillegas added a comment -

        Hi Kim,

        I agree with this conclusion of yours: "It is probably a lot safer to do what we generally do in the Reference Manual, to say something like 'For more information, see the public API javadoc for org.apache.derby.catalog.SequencePreallocator.'" Note that this will require adding the javadoc for the diagnostic VTIs to the public API. Currently, the diagnostic VTIs only appear in the full engine javadoc. Thanks.

        Show
        Rick Hillegas added a comment - Hi Kim, I agree with this conclusion of yours: "It is probably a lot safer to do what we generally do in the Reference Manual, to say something like 'For more information, see the public API javadoc for org.apache.derby.catalog.SequencePreallocator.'" Note that this will require adding the javadoc for the diagnostic VTIs to the public API. Currently, the diagnostic VTIs only appear in the full engine javadoc. Thanks.
        Hide
        Kim Haase added a comment -

        Way down at the bottom of the docs page are links to the development versions of the full engine javadoc under "Internal API documentation." Would it make sense to refer to that for info about the engine APIs?

        Show
        Kim Haase added a comment - Way down at the bottom of the docs page are links to the development versions of the full engine javadoc under "Internal API documentation." Would it make sense to refer to that for info about the engine APIs?
        Hide
        Rick Hillegas added a comment -

        Hi Kim,

        In general, the engine javadoc is assumed to not be stable. It changes from one release to another. I don't think that the user guides should refer people to unstable javadoc. The only javadoc mentioned by the user guides should be javadoc that is in the public api or that is included wholesale in the user guides themselves. Maybe what we need to do is log a related JIRA so that a developer can add the diagnostic VTI javadoc to the public api. Thanks.

        Show
        Rick Hillegas added a comment - Hi Kim, In general, the engine javadoc is assumed to not be stable. It changes from one release to another. I don't think that the user guides should refer people to unstable javadoc. The only javadoc mentioned by the user guides should be javadoc that is in the public api or that is included wholesale in the user guides themselves. Maybe what we need to do is log a related JIRA so that a developer can add the diagnostic VTI javadoc to the public api. Thanks.
        Hide
        Kim Haase added a comment -

        Yes, it might make sense to do for the LockTable API (and the other org.apache.derby.diag classes) what you did for the SequencePreallocator API so that it can be found in the regular JDBC API docs. I notice for org.apache.derby.catalog you exposed only that one interface.

        If you think it is useful to expose the diag classes (is it?), then please create an issue to do so. We would then want to mention the API docs in the topic http://db.apache.org/derby/docs/10.9/ref/rrefsyscsdiagtables.html.

        Show
        Kim Haase added a comment - Yes, it might make sense to do for the LockTable API (and the other org.apache.derby.diag classes) what you did for the SequencePreallocator API so that it can be found in the regular JDBC API docs. I notice for org.apache.derby.catalog you exposed only that one interface. If you think it is useful to expose the diag classes (is it?), then please create an issue to do so. We would then want to mention the API docs in the topic http://db.apache.org/derby/docs/10.9/ref/rrefsyscsdiagtables.html .
        Hide
        Rick Hillegas added a comment -

        Thinking more about this, I wonder why the Developer's Guide needs to link to the LockTable javadoc at all. It seems to me that the only reason to consult that javadoc is because the Reference Manual does not describe this diagnostic vti in sufficient detail. The Reference Manual does bother to document SPACE_TABLE in greater detail, telling the user what the returned columns mean. Instead of adding these diagnostic vtis to the public api, it might make more sense to beef up the descriptions in the "SYSCS_DIAG diagnostic tables and functions" section of the Reference Manual.

        Beefing up the description of LOCK_TABLE would just involve copying the header information from LockTable into the Reference Manual. The other, under-documented vtis could be handled similarly.

        Show
        Rick Hillegas added a comment - Thinking more about this, I wonder why the Developer's Guide needs to link to the LockTable javadoc at all. It seems to me that the only reason to consult that javadoc is because the Reference Manual does not describe this diagnostic vti in sufficient detail. The Reference Manual does bother to document SPACE_TABLE in greater detail, telling the user what the returned columns mean. Instead of adding these diagnostic vtis to the public api, it might make more sense to beef up the descriptions in the "SYSCS_DIAG diagnostic tables and functions" section of the Reference Manual. Beefing up the description of LOCK_TABLE would just involve copying the header information from LockTable into the Reference Manual. The other, under-documented vtis could be handled similarly.
        Hide
        Kim Haase added a comment -

        That sounds like a great idea, Rick. I will do what we did for SPACE_TABLE.

        Actually, it makes me wonder if we should divide the "SYSCS_DIAG diagnostic tables and functions" topic into subtopics, one for each of the tables and table functions. It's getting rather large. Maybe not right this minute, though.

        Show
        Kim Haase added a comment - That sounds like a great idea, Rick. I will do what we did for SPACE_TABLE. Actually, it makes me wonder if we should divide the "SYSCS_DIAG diagnostic tables and functions" topic into subtopics, one for each of the tables and table functions. It's getting rather large. Maybe not right this minute, though.
        Hide
        Knut Anders Hatlen added a comment -

        +1 to dividing it into subtopics. That has bothered me in the past, both because I didn't find the diagnostic tables in the ToC, and because I couldn't provide direct links to specific diagnostics tables.

        Show
        Knut Anders Hatlen added a comment - +1 to dividing it into subtopics. That has bothered me in the past, both because I didn't find the diagnostic tables in the ToC, and because I couldn't provide direct links to specific diagnostics tables.
        Hide
        Kim Haase added a comment -

        Thanks, Knut – I will divide it. Most of the tables have multiple columns and it makes sense to provide information about them.

        Show
        Kim Haase added a comment - Thanks, Knut – I will divide it. Most of the tables have multiple columns and it makes sense to provide information about them.
        Hide
        Kim Haase added a comment -

        Well, this turned into a major project!

        Attaching DERBY-6065.diff, DERBY-6065.stat, and DERBY-6065.zip, with changes as follows:

        M src/devguide/cdevconcepts50894.dita
        M src/adminguide/radminjmxintro.dita
        M src/adminguide/radminjmxcode.dita
        M src/adminguide/radminjmxenablepolicy.dita
        A src/ref/rrefsyscsdiagcontainedroles.dita
        A src/ref/rrefsyscsdiagerrormessages.dita
        A src/ref/rrefsyscsdiagspacetable.dita
        A src/ref/rrefsyscsdiagerrorlogreader.dita
        M src/ref/rrefsyscsdiagtables.dita
        M src/ref/refderby.ditamap
        A src/ref/rrefsyscsdiaglocktable.dita
        A src/ref/rrefsyscsdiagtransactiontable.dita
        A src/ref/rrefsyscsdiagstatementduration.dita
        M src/ref/rrefproperpreallocator.dita
        A src/ref/rrefsyscsdiagstatementcache.dita

        I also updated the wiki page referred to in the Developer's Guide topic to remove any doc links below the top level manuals page, replacing them with manual titles and topic titles if appropriate.

        Please let me know if any fixes are needed.

        Show
        Kim Haase added a comment - Well, this turned into a major project! Attaching DERBY-6065 .diff, DERBY-6065 .stat, and DERBY-6065 .zip, with changes as follows: M src/devguide/cdevconcepts50894.dita M src/adminguide/radminjmxintro.dita M src/adminguide/radminjmxcode.dita M src/adminguide/radminjmxenablepolicy.dita A src/ref/rrefsyscsdiagcontainedroles.dita A src/ref/rrefsyscsdiagerrormessages.dita A src/ref/rrefsyscsdiagspacetable.dita A src/ref/rrefsyscsdiagerrorlogreader.dita M src/ref/rrefsyscsdiagtables.dita M src/ref/refderby.ditamap A src/ref/rrefsyscsdiaglocktable.dita A src/ref/rrefsyscsdiagtransactiontable.dita A src/ref/rrefsyscsdiagstatementduration.dita M src/ref/rrefproperpreallocator.dita A src/ref/rrefsyscsdiagstatementcache.dita I also updated the wiki page referred to in the Developer's Guide topic to remove any doc links below the top level manuals page, replacing them with manual titles and topic titles if appropriate. Please let me know if any fixes are needed.
        Hide
        Rick Hillegas added a comment -

        Thanks for this patch, Kim. I noticed one cut-and-paste problem:

        rrefsyscsdiagtransactiontable

        • The name of the table should be TRANSACTION_TABLE rather than
          STATEMENT_CACHE
        Show
        Rick Hillegas added a comment - Thanks for this patch, Kim. I noticed one cut-and-paste problem: rrefsyscsdiagtransactiontable The name of the table should be TRANSACTION_TABLE rather than STATEMENT_CACHE
        Hide
        Kim Haase added a comment -

        Thanks for catching that, Rick! I think what I will do is commit this patch first and then file a smaller one to fix this typo (and any others like it).

        Show
        Kim Haase added a comment - Thanks for catching that, Rick! I think what I will do is commit this patch first and then file a smaller one to fix this typo (and any others like it).
        Hide
        Kim Haase added a comment -

        In fact there is a similar cut/paste error for ERROR_MESSAGES.

        Show
        Kim Haase added a comment - In fact there is a similar cut/paste error for ERROR_MESSAGES.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-6065.diff to documentation trunk at revision 1443747.

        Show
        Kim Haase added a comment - Committed patch DERBY-6065 .diff to documentation trunk at revision 1443747.
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6065-2.diff, DERBY-6065-2.stat, and DERBY-6065-2.zip, with table title fixes in these topics:

        M src/ref/rrefsyscsdiagtransactiontable.dita
        M src/ref/rrefsyscsdiagerrormessages.dita

        Show
        Kim Haase added a comment - Attaching DERBY-6065 -2.diff, DERBY-6065 -2.stat, and DERBY-6065 -2.zip, with table title fixes in these topics: M src/ref/rrefsyscsdiagtransactiontable.dita M src/ref/rrefsyscsdiagerrormessages.dita
        Hide
        Kim Haase added a comment -

        I'll commit this second patch in the next day or so, but would be happy to hear of anything else that needs fixing.

        One puzzle: in the table for the SYSCS_DIAG.STATEMENT_CACHE diagnostic table, in the description of the UNICODE column, the explanation of the true value is in the present tense, but the explanation of the false value is in the past tense. Is there a reason for this? I copied the values right out of the description of the org.apache.derby.diag.StatementCache class under https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/index.html.

        Show
        Kim Haase added a comment - I'll commit this second patch in the next day or so, but would be happy to hear of anything else that needs fixing. One puzzle: in the table for the SYSCS_DIAG.STATEMENT_CACHE diagnostic table, in the description of the UNICODE column, the explanation of the true value is in the present tense, but the explanation of the false value is in the past tense. Is there a reason for this? I copied the values right out of the description of the org.apache.derby.diag.StatementCache class under https://builds.apache.org/job/Derby-trunk/lastSuccessfulBuild/artifact/trunk/javadoc/engine/index.html .
        Hide
        Rick Hillegas added a comment -

        Hi Kim,

        Thanks for thinking about this puzzling wording. You're right, it doesn't make any sense. Looking at the code, I see that the column is vacuous because it always contains true. So the explanation of the column should just be "always true". According to the code, once upon a time the column was not vacuous. But that was before Derby was open-sourced. Thanks.

        Show
        Rick Hillegas added a comment - Hi Kim, Thanks for thinking about this puzzling wording. You're right, it doesn't make any sense. Looking at the code, I see that the column is vacuous because it always contains true. So the explanation of the column should just be "always true". According to the code, once upon a time the column was not vacuous. But that was before Derby was open-sourced. Thanks.
        Hide
        Kim Haase added a comment -

        Thanks, Rick, that's very helpful – I'll revise the patch.

        I guess the wording should also be fixed in the javadoc for the class? Should I try to make a patch for that too?

        Show
        Kim Haase added a comment - Thanks, Rick, that's very helpful – I'll revise the patch. I guess the wording should also be fixed in the javadoc for the class? Should I try to make a patch for that too?
        Hide
        Rick Hillegas added a comment -

        Thanks, Kim. Fixing the javadoc sounds good. +1

        Show
        Rick Hillegas added a comment - Thanks, Kim. Fixing the javadoc sounds good. +1
        Hide
        Kim Haase added a comment -

        Overwriting the previous DERBY-6065-2.diff, DERBY-6065-2.stat, and DERBY-6065-2.zip with the addition of the fix to the StatementCache column description.

        I'll work on the javadoc patch.

        Show
        Kim Haase added a comment - Overwriting the previous DERBY-6065 -2.diff, DERBY-6065 -2.stat, and DERBY-6065 -2.zip with the addition of the fix to the StatementCache column description. I'll work on the javadoc patch.
        Hide
        Kim Haase added a comment -

        And here is a patch for the StatementCache javadoc, DERBY-6065-code.diff, along with the output file, StatementCache.html. Hope it works!

        Thanks for all your help, Rick!

        Show
        Kim Haase added a comment - And here is a patch for the StatementCache javadoc, DERBY-6065 -code.diff, along with the output file, StatementCache.html. Hope it works! Thanks for all your help, Rick!
        Hide
        Rick Hillegas added a comment -

        +1 to the code patch, Kim. Thanks!

        Show
        Rick Hillegas added a comment - +1 to the code patch, Kim. Thanks!
        Hide
        Kim Haase added a comment -

        Committed DERBY-6065-2.diff (the doc patch) to documentation trunk at revision 1444141.

        Show
        Kim Haase added a comment - Committed DERBY-6065 -2.diff (the doc patch) to documentation trunk at revision 1444141.
        Hide
        Kim Haase added a comment -

        Committed DERBY-6065-code.diff to code trunk at revision 1444154.

        Thanks again, Rick. I can reopen this issue if anyone finds more things to correct.

        Show
        Kim Haase added a comment - Committed DERBY-6065 -code.diff to code trunk at revision 1444154. Thanks again, Rick. I can reopen this issue if anyone finds more things to correct.
        Hide
        Kim Haase added a comment -

        Closing, since the changes appeared in the 10.10.1.1 documentation.

        Show
        Kim Haase added a comment - Closing, since the changes appeared in the 10.10.1.1 documentation.

          People

          • Assignee:
            Kim Haase
            Reporter:
            Bryan Pendleton
          • Votes:
            0 Vote for this issue
            Watchers:
            5 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development