#304 NDOC Parser - Links un-resolved throughout

v1.0_(example)
closed-fixed
nobody
None
5
2016-04-18
2013-12-13
StevenAZ
No

Found in 1.4.8:

In areas where links should exist, the lookup is failing and the HTML is displayed with a <some_signal> name.

Discussion

  • Matthew Ballance

    Can you supply a testcase? That would definitely help me understand the issue.

    -Matthew

     
  • StevenAZ

    StevenAZ - 2013-12-14

    The project attached has a very simple project. It is a single package file. Within the project is a class, which has a multiply and divide function. In the footer of the NDOC comment is a "See Also: <mult>" which is supposed to link to the NDOC multiply function.

    From what I can tell, the function buildTextLink in HTMLFromNDMarkup.java is unable to derive the link because it can't find the generated symbol in the symbol table.

    When you look at the generated HTML, you'll see <mult> instead of a link in the description of the "div" task. Easiest way to get there is to look at the list of functions.

     
    Last edit: StevenAZ 2013-12-14
  • Matthew Ballance

    Okay, after digging into this a bit, there appears to be a small issue with the testcase: the class name (class_w) used in the documentation comment doesn't match the actual class name (classw). After changing the doc comment to use 'classw', the links appear to display correctly.

    Not sure if the behavior you see in your environment is due to a similar situation. This does seem like a case that would merit some additional checks to help the user identify and correct mismatched doc comments.

     
  • StevenAZ

    StevenAZ - 2013-12-16

    My apologies for the junk testcase. Completely wasted your time. I saw what I was seeing at work, and didn't stop to check that the case was the same. The attachment below, is pretty much the same as the previous case, with a second file. The second file contains a program and a module.

    I am not even sure what the expected behavior should be. What I am seeing is that the program and module appear in the generated documentation. The links in the generated docs are not linked (see documentation in mod_fnc2).

    I quite like seeing the module documentation... but not sure if it should be there. It was these links that I was chasing down, not links within the class. I had just assumed these were equivalent, and stopped when I had a simple testcase that showed the behavior I expected.

     
  • StevenAZ

    StevenAZ - 2013-12-16

    Adding another zip file... this is probably a better one to look at. I have added another package to the project. When selecting a_package as the package I want to generate docs for, I get the another_package information generated too.

    In the example below, a_package div is shown, as well as the div (without hierarchy information) from another_pacakge.

    div a_package::classw::div
    div div
    
     
  • Matthew Ballance

    Thanks for the testcase. I hadn't really looked into the full-document natural-docs generator before, so this has been an interesting exercise.

    It appears that the docs generator only builds symbol-index information for contents of the selected packages. That appears to be the immediate reason that references within modules are unresolved.

    I'm also a little unsure when and how much module documentation should be included. Should the doc-gen wizard give a global option to include/exclude module docs?

    I'll look into enhancing the symbol-collection code to collect symbols from modules. This should resolve the immediate issue.

     
  • Armond

    Armond - 2013-12-21

    If I'm understanding correctly, there are two issues at hand here:

    1) The "See Also" links invalid.

    Importing the attached testcase project on the current mainline head-of-tree, the "See Also" links appear to be getting generated just fine. In this case though, the target of the links is just above the link itself, so the browser doesn't load another page or even scroll because the target is already visible. Could that be what was occurring in the case of initial filing? Or, Mathew, have you already added the module symbol collection as mentioned above?

    2) Support of selecting specific packages to generate docs for.

    I'd have to look more closely at the current source, but last I recall, document generation ignored the package selection in the doc gen wizard, generating documents for all packages in the project. In other words, package selection was not yet implemented.

    I'll revisit the source this weekend to get back up-to-speed.

     
  • Matthew Ballance

    Have a look at mod_fnc2. At least for me, the generated doc shows:

    This is a function in module.

    See Also

    < mod_fnc2 > < mod_var2 >

    In this case, the links for 'See Also' references for a module item are not resolved. Do you see the same on your end?

     
  • Armond

    Armond - 2013-12-22

    I was able to reproduce. Fixes are under way.

     
  • StevenAZ

    StevenAZ - 2016-04-18
    • status: open --> closed-fixed
     
  • StevenAZ

    StevenAZ - 2016-04-18

    Looks like it was fixed some time in the past... closing item. (written on 1.8.3)

     

Log in to post a comment.

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks