Xref a Generic class / method

[RohitM-IN]

Hi,

I am new to this wyam & statiq and need help with linking the generic api class
I have a ref

[`Result<T>`](xref:api-DbSyncKit.Core.DataContract.Result)

how do i get the link of it

i tried

xref:api-DbSyncKit.Core.DataContract.Result`1
xref:api-DbSyncKit.Core.DataContract.Result<T>
xref:api-DbSyncKit.Core.DataContract.Result(T)
xref:api-DbSyncKit.Core.DataContract.Result`T

this is the class that it refers to

other are working like xref:api-DbSyncKit.Core works perfectly fine

also how do i refrence a property

DbSyncKit.DB.Attributes.GenerateInsertWithIDAttribute.IncludeIdentityInsert

it gives Couldn't find document with xref "DbSyncKit.DB.Attributes.GenerateInsertWithIDAttribute.IncludeIdentityInsert"

[daveaglick]

This is a great question - it actually made me write some extra tests to verify my understanding about how the code analysis xrefs are generated.

In answer to you first question about generic class xrefs, I'm surprised xref:api-DbSyncKit.Core.DataContract.Result<T> isn't working. The unit test I rigged up seems to suggest that's correct:

If I had to guess, I'm wondering if the use of angle brackets here is getting in the way since those are relatively loaded as a symbol for web stuff. For example, perhaps they're getting escaped before the xref resolver bits can convert the link. I'm going to try some stuff to get to the bottom of that and will report back. I may end up converting angle brackets to something else like dashes for xref purposes (which I'll need to make sure to document well).

I'm also a little stumped about member xrefs right now. You're correct that those aren't working as intended, but I'm still not sure why. I've got a failing unit test now, so I just need to dig into it and see what's going on. This could get a little tricky though with things like method overloads. If you notice, all members end up with a numerical code that's a hash of their fully qualified name. I might end up using that as a part of the xref, which means you'd need to generate the docs to see what that code is, and then use that. Still thinking about this one.

[RohitM-IN]

guess what it is

api-DbSyncKit.Core.Synchronization.GetSqlQueryForSyncData-T-(DbSyncKit.Core.DataContract.Result-T-, System.Int32)

and it outputted as

I removed the space between and it changed back to link but now

 - Couldn't find document with xref "api-DbSyncKit.Core.Synchronization.GetSqlQueryForSyncData-T-(DbSyncKit.Core.DataContract.Result-T-,System.Int32)"

I guess it will need to remove the space in between or it displays as text XD

---

but man you should add this tip in the docs

that if you are unsure what the page url looks like just add

<div>@Document.GetString("xref")</div>

to the shared footer and it will give its xref for that page only man this is good XD

[Foxtrek64]

Been sort of following this in the background. Using dashes feels strange to me but at the same time, I'm not sure what else I'd use.

HTML uses angle brackets, which is the cause of this issue.
Javadocs uses curly braces, e.g. <see cref="Task{T}"/>, but I think this may cause other issues being a reserved character as well.
A single back tick ` might work, but I worry about it conflicting with Markdown processing.
Square brackets make it look like an accessor rather than a type parameter, so that may work but it'd probably just add confusion.

Suppose we could always use a 😄 emoji GetSqlQueryForSyncData😄T😄() /jk

Overall, I think hyphen is probably the best option here.

[daveaglick]

Suppose we could always use a 😄 emoji GetSqlQueryForSyncData😄T😄() /jk

Wish I'd thought of that! LGTM.

Overall, I think hyphen is probably the best option here.

Yeah, I went through a pretty similar thought process as you. Hyphens aren't awesome, but they're less not-awesome than other alternatives I could think of, and in the end it's just for xrefs in specific cases so it's not a thing that's going to be used super frequently.

[girlpunk]

You might need opening and closing characters to be different, so obviously the solution is GetSqlQueryForSyncData👉T👈()

[daveaglick]

so obviously the solution is GetSqlQueryForSyncData👉T👈()

I'm so tempted to hit the "Mark as answer" button on this.