Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reference to Task.Delay(int) not resolved #4164

Open
lg2de opened this Issue Mar 14, 2019 · 12 comments

Comments

Projects
None yet
3 participants
@lg2de
Copy link

lg2de commented Mar 14, 2019

Operation System: Windows
DocFX Version Used: 2.40.12.0
Template used: custom

Steps to Reproduce:

  1. download xrefmap.yml into docs.microsoft.com.zip
  2. add docs.microsoft.com.zip to docfx.json as xref
  3. add following reference to c# class:
    /// <summary>
    ///     Implements <see cref="ITimer" /> using <see cref="Task.Delay(int)" />.
    /// </summary>

Expected Behavior:
Reference to Task.Delay is added.

Actual Behavior:
[19-03-14 01:27:35.033]Warning:[MetadataCommand.ExtractMetadata]Invalid cref value "!:Task.Delay(Int32)" found in triple-slash-comments for TaskTimer defined in ../../src/AIS.TC.Core/TaskTimer.cs Line 13, ignored.
Reference to ITimer (internal interface) and other classes from .NET (Core) Framework is working fine.

generated yml content:
summary: "\nImplements <xref href=\"AIS.TC.Core.ITimer\" data-throw-if-not-resolved=\"false\"></xref> using <see cref=\"!:Task.Delay(Int32)\"></see>.\n"

I also tried to reference Task.Delay(Int32).

@superyyrrzz

This comment has been minimized.

Copy link
Collaborator

superyyrrzz commented Mar 14, 2019

!: means the compiler cannot understand the cref. I guess you did not add using System.Threading.Tasks;. Try adding this.

After the warning is gone, you can try use the xrefService. I am not sure whether the zipped YAML file can work.

@lg2de

This comment has been minimized.

Copy link
Author

lg2de commented Mar 14, 2019

System.Threading.Tasks is in the using list.

The zipped YAML file seams to work for many, many other types.

@superyyrrzz

This comment has been minimized.

Copy link
Collaborator

superyyrrzz commented Mar 14, 2019

I failed to reproduce this issue. It works fine for me:
image

Could you provide a sample project?

@lg2de

This comment has been minimized.

Copy link
Author

lg2de commented Mar 14, 2019

@superyyrrzz

This comment has been minimized.

Copy link
Collaborator

superyyrrzz commented Mar 15, 2019

As I commented, relace

    "xref": [
      "file://help/help/xrefmaps/docs.microsoft.com.zip"
    ],

with

    "xrefService": [
      "https://xref.docs.microsoft.com/query?uid={uid}"
    ],

then all is fine.

@bitbonk

This comment has been minimized.

Copy link
Contributor

bitbonk commented Mar 15, 2019

I really fear that using a xrefService via the internet for each and every API that we reference somewhere in our documentation will significantly slow down the build time. Also, if the internet breaks, our builds break.

Is there no reliable way to have an offline build?

@bitbonk

This comment has been minimized.

Copy link
Contributor

bitbonk commented Mar 15, 2019

@superyyrrzz

This comment has been minimized.

Copy link
Collaborator

superyyrrzz commented Mar 15, 2019

@bitbonk I agree this is a valid concern. v3 has a similar idea to download needed xrefMap in a pre step to avoid call API during build. This will make the build input clear.

Fow now, xrefService is the source of truth that contains the full data. XrefMap on docs site contains only partial data. The tradeoff here is: If I only need to resolve few BCL UIDs, I want to use xrefService instead of preparing the huge xrefMap beforehand. If I need to resolve a lot, xrefMap would be better.

@lg2de

This comment has been minimized.

Copy link
Author

lg2de commented Mar 15, 2019

I expect to need resolving many UIDs. This is why I would like to get the faster solution.
When the v3 will be available?

@superyyrrzz

This comment has been minimized.

Copy link
Collaborator

superyyrrzz commented Mar 17, 2019

You can refer to the roadmap.

Have you tried to reference to xrefmap.yml directly? "xref": "xrefmap.yml"

@lg2de

This comment has been minimized.

Copy link
Author

lg2de commented Mar 18, 2019

Just now I did the following verification:

  1. use xrefService instead of xref => same Problem as initially reported
  2. use xrefmap.yml instead of xrefmap.zip => same result

So, it seems the problem is neither related to ZIP or YML or SERVICE.

@superyyrrzz

This comment has been minimized.

Copy link
Collaborator

superyyrrzz commented Mar 20, 2019

Maybe you can try running docfx append -f, to disable incremental build.

Or you can try this xrefmap.yml for test (which works for me):

### YamlMime:XRefMap
references:
- uid: System.Threading.Tasks.Task.Delay(System.Int32)
  name: Delay(Int32)
  href: https://docs.microsoft.com/dotnet/api/system.threading.tasks.task.delay#System_Threading_Tasks_Task_Delay_System_Int32_
  fullName: System.Threading.Tasks.Task.Delay(Int32)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.