Ejemplo n.º 1
0
        public static async Task ApplyDocumentation(IDocProvider?docProvider, DocItemCache cache, CsAssembly module,
                                                    DocumentationContext context)
        {
            var documentationTasks = new List <Task>();

            Task DocumentSelector(CsBase cppElement) =>
            DocumentElement(docProvider, cache, cppElement, context, true, null);

            foreach (var cppInclude in module.Namespaces)
            {
                documentationTasks.AddRange(cppInclude.Enums.Select(DocumentSelector));
                documentationTasks.AddRange(cppInclude.Structs.Select(DocumentSelector));
                documentationTasks.AddRange(
                    cppInclude.Interfaces
                    .Select(cppInterface => DocumentInterface(docProvider, cache, cppInterface, context))
                    );
                documentationTasks.AddRange(
                    cppInclude.Classes
                    .Select(cppFunction => DocumentGroup(docProvider, cache, cppFunction, context))
                    );
            }

            await Task.WhenAll(documentationTasks);
        }
Ejemplo n.º 2
0
        private static async Task <IDocItem?> DocumentElement(IDocProvider?docProvider,
                                                              DocItemCache cache,
                                                              CsBase element,
                                                              DocumentationContext context,
                                                              bool documentInnerElements,
                                                              string?name)
        {
            var docName = name ?? element.CppElementName;

            if (string.IsNullOrEmpty(docName))
            {
                return(null);
            }

            docName = docName.Trim();

            if (string.IsNullOrEmpty(docName))
            {
                return(null);
            }

            var cacheEntry = cache.Find(docName);
            var docItem    = cacheEntry ?? await QueryDocumentationProvider();

            if (docItem == null)
            {
                return(null);
            }

            element.DocId       = docItem.ShortId;
            element.Description = docItem.Summary;
            element.Remarks     = docItem.Remarks;
            docItem.Names.Add(docName);

            if (cacheEntry == null)
            {
                cache.Add(docItem);
            }

            if (element.Items.Count == 0)
            {
                return(docItem);
            }

            if (documentInnerElements)
            {
                DocumentInnerElements(element.Items, docItem);
            }

            return(docItem);

            async Task <IDocItem?> QueryDocumentationProvider()
            {
                if (docProvider == null)
                {
                    return(null);
                }

                Lazy <string> docProviderName = new(
                    () =>
                {
                    try
                    {
                        var friendlyName = docProvider.UserFriendlyName;
                        return(string.IsNullOrWhiteSpace(friendlyName) ? FullName() : friendlyName);
                    }
                    catch
                    {
                        return(FullName());
                    }

                    string FullName()
                    {
                        var type = docProvider.GetType();
                        var name = type.FullName;
                        return(string.IsNullOrEmpty(name) ? type.Name : name !);
                    }
                },
                    LazyThreadSafetyMode.None
                    );

                List <Exception> exceptions = new(3);

                var(backoff, backoffIndex, nextDelay) = GenerateBackoff(TimeSpan.Zero);

                try
                {
                    for (uint retry = 0; retry <= 5; retry++)
                    {
                        if (retry != 0)
                        {
                            TimeSpan delay;
                            if (nextDelay.HasValue)
                            {
                                delay = nextDelay.Value;
                            }
                            else
                            {
                                // TODO: fix the bug and remove this hack
                                if (backoffIndex >= 5)
                                {
                                    context.Logger.Message(
                                        $"SharpGen internal invalid state on delay: backoffIndex == {backoffIndex}"
                                        );
                                    if (Debugger.IsAttached)
                                    {
                                        Debugger.Break();
                                    }
                                    backoffIndex = 0;
                                }

                                delay = backoff[backoffIndex++];
                            }
                            if (delay > TimeSpan.Zero)
                            {
                                await Task.Delay(delay);
                            }
                            nextDelay = null;
                        }

                        try
                        {
                            var result = await docProvider.FindDocumentationAsync(docName, context);

                            switch (result)
                            {
                            case null:
                                throw new ArgumentNullException(
                                          nameof(result),
                                          $"Unexpected null {nameof(IFindDocumentationResult)}"
                                          );

                            case FindDocumentationResultFailure resultFailure:
                            {
                                var retryDelay = resultFailure.RetryDelay;
                                if (retryDelay == TimeSpan.MaxValue)
                                {
                                    return(null);
                                }

                                if (retryDelay <= TimeSpan.Zero)
                                {
                                    nextDelay = TimeSpan.Zero;
                                }

                                // TODO: fix the bug and remove this hack
                                if (backoffIndex >= 5)
                                {
                                    context.Logger.Message(
                                        $"SharpGen internal invalid state on reschedule: backoffIndex = {backoffIndex}"
                                        );
                                    if (Debugger.IsAttached)
                                    {
                                        Debugger.Break();
                                    }
                                    (backoff, backoffIndex, nextDelay) = GenerateBackoff(retryDelay);
                                }

                                nextDelay = backoff[backoffIndex++];

                                if (nextDelay < retryDelay)
                                {
                                    (backoff, backoffIndex, nextDelay) = GenerateBackoff(retryDelay);
                                }

                                break;
                            }

                            case FindDocumentationResultSuccess resultSuccess:
                                return(resultSuccess.Item);    // TODO: check if the item is empty (therefore, useless)

                            default:
                                throw new ArgumentOutOfRangeException(
                                          nameof(result),
                                          $"Unexpected {nameof(IFindDocumentationResult)}: {result.GetType().FullName}"
                                          );
                            }
                        }
                        catch (Exception e)
                        {
                            e.Data["SDK:" + nameof(docProvider)]           = docProvider;
                            e.Data["SDK:" + nameof(docName)]               = docName;
                            e.Data["SDK:" + nameof(context)]               = context;
                            e.Data["SDK:" + nameof(retry)]                 = retry;
                            e.Data["SDK:" + nameof(backoffIndex)]          = backoffIndex;
                            e.Data["SDK:" + nameof(exceptions) + ".Count"] = exceptions.Count;

                            exceptions.Add(e);

                            // We should retry less when it's due to unhandled exception.
                            // So in exception case we step twice in retry count on each iteration.
                            retry++;
                        }
                    }

                    context.Logger.Message($"{docProviderName.Value} extension failed to find documentation for \"{docName}\"");

                    return(null);
                }
                finally
                {
                    if (exceptions.Count > 0)
                    {
                        var failure = new DocumentationQueryFailure(docName)
                        {
                            Exceptions                    = exceptions,
                            FailedProviderName            = docProviderName.Value,
                            TreatProviderFailuresAsErrors = docProvider.TreatFailuresAsErrors
                        };

                        context.Failures.Add(failure);
                    }
                }
            }
        }