docs: def comment_to_ast(self, comment, link_resolver):
          """
          Given a gtk-doc comment string, returns an opaque PyCapsule
          containing the document root.
  
          This is an optimization allowing to parse the docstring only
          once, and to render it multiple times with
          `ast_to_html`, links discovery and
          most of the link resolution being lazily done in that second phase.
  
          If you don't care about performance, you should simply
          use `translate`.
  
          Args:
              text: unicode, the docstring to parse.
              link_resolver: hotdoc.core.links.LinkResolver, an object
                  which will be called to retrieve `hotdoc.core.links.Link`
                  objects.
  
          Returns:
              capsule: A PyCapsule wrapping an opaque C pointer, which
                  can be passed to `ast_to_html`
                  afterwards.
              diagnostics: A list of diagnostics as output by the gtk-doc cmark
                  extension
          """
          assert comment is not None
  
          text = comment.description
  
          if (self.remove_xml_tags or comment.filename in
                  self.gdbus_codegen_sources):
              text = re.sub('<.*?>', '', text)
  
          if self.escape_html:
              # pylint: disable=deprecated-method
              text = cgi.escape(text)
          ast, diagnostics = cmark.gtkdoc_to_ast(text, link_resolver)
  
          for diag in diagnostics:
              if (comment.filename and comment.filename not in
                      self.gdbus_codegen_sources):
                  column = diag.column + comment.col_offset
                  if diag.lineno == 0:
                      column += comment.initial_col_offset
  
                  lines = text.split('\n')
                  line = lines[diag.lineno]
                  i = 0
                  while line[i] == ' ':
                      i += 1
                  column += i - 1
  
                  if diag.lineno > 0 and any([c != ' ' for c in
                                              lines[diag.lineno - 1]]):
                      column += 1
  
                  lineno = -1
                  if comment.lineno != -1:
                      lineno = (comment.lineno - 1 + comment.line_offset +
                                diag.lineno)
                  warn(
                      diag.code,
                      message=diag.message,
                      filename=comment.filename,
                      lineno=lineno,
                      column=column)
  
          return ast