Skip to content
This repository

@uses and @throws aren't resolving resource names #920

Open
slifty opened this Issue · 8 comments

4 participants

Daniel Schultz Vasil Rangelov Mike van Riel
Daniel Schultz
slifty commented

Apologies if this isn't proper protocol.

I'm facing an issue with @uses and @throws where the resource is not appearing in the documentation, but the description is.

For example:

This DocBlock:

/**
 * Constructs the object and loads data.
 * 
 * This constructor invokes the gatherData and populates the object's instance variables.
 *
 * @uses gatherData() to load in the data associated with this object.
 * @uses load() to populate the data gathered.
 * @param integer $itemId Is the item being loaded.
 */

Yields this output:

example

Which has no mention of the methods being used. Just the descriptions provided.

Please note that gatherData() and load() are both methods of the class in question. I have also tried specifying the class explicitly using ClassName::gatherData() and face the same problem.

I can't figure out if I'm misusing the tool, or if it is an error in the code itself.

Note: I posted this as a StackOverflow question as well (http://stackoverflow.com/questions/17504923/uses-and-throws-arent-resolving-in-phpdocumentor)

I see the same thing with phpDocumentor version 2.0.0b6 (installed via pear). The generated tag in structure.xml looks like this for a similar line:

<tag name="uses" description="some description" line="532"/>

While the information seems to be parsed correctly, if i dump the $reflectionTag here and the getReference() returns it as well.

Could be related to #640 ?

Vasil Rangelov

@complex857

Whenever there's a structure.xml issue, you can blame it on the XML writer.

We have some ways to go on reimplementing tag specific serialization, but that's merely because there are more important priorities at this point (like, getting @see, and by extension, @uses to work properly with the responsive-twig template, so no, this is not related to #640).

Daniel Schultz
slifty commented

Got it! I'd be glad to spend some time trying to write a patch if you think this is an issue that a new contributor would be able to help with. Any pointers to areas of code worth inspecting would be helpful if you have time for that!

If it's too deep I understand as well.

Vasil Rangelov

Sure. Patches are always greatly appreciated.

As far as the structure.xml issue is concerned, I already said it's the XML writer (linked above).

As far as the other issues are concerned, I'm not so sure (or I probably would've fixed them already myself). They're a combination of missing "special treatment" for these tags in the template, combined with the fact that we don't (yet) convert tags that ReflectionDocBlock knows, but PhpDocumentor doesn't (with @see, @uses and @throws being in that list). How exactly do we do such conversion efficiently is the tricky part.

Mike van Riel
Owner
mvriel commented

@slifty it is the buildDocBlockTag function in https://github.com/phpDocumentor/phpDocumentor2/blob/release-2.0/src/phpDocumentor/Plugin/Core/Transformer/Writer/Xml.php#L616 that is responsible for writing tags to the XML file. It appears that handling of the Referenced to attributes is not handled correctly.

Regarding the missing resources in the Twig based template; this will be fixed with next release. I am now fixing that issue

Mike van Riel
Owner
mvriel commented

I have fixed the missing @uses and @throws references, not all of them resolve to links but that is due to issue #915. I will fix that in that issue.

@slifty What remains is the missing links in the structure.xml; I have explicitly not fixed those since I wasn't sure that you were going to pick that up (which would be awesome!)

Daniel Schultz
slifty commented

@mvriel Sorry for the delay! I'll try to find a few hours to dig into the structure.xml tomorrow -- Will need to take some time to get familiarized with the project but would love to try contributing.

Mike van Riel
Owner
mvriel commented

That would be super! Let me know if you have any questions, I'd be happy to answer them

Siad Ardroumli siad007 referenced this issue in phpDocumentor/template.responsive
Merged

Add uses to template #45

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.