From 436eb28d9f7af82eadc86e71915109e6dcc7b5b2 Mon Sep 17 00:00:00 2001
From: Anthony Johnson <aj@ohess.org>
Date: Tue, 18 Aug 2015 14:30:08 -0700
Subject: [PATCH] Parse out doc id prefixes and add reference types

---
 autoapi/mappers/dotnet.py | 76 +++++++++++++++++++++++++++------------
 tests/test_domains.py     | 12 ++++---
 2 files changed, 62 insertions(+), 26 deletions(-)

diff --git a/autoapi/mappers/dotnet.py b/autoapi/mappers/dotnet.py
index 859b29c..6766294 100644
--- a/autoapi/mappers/dotnet.py
+++ b/autoapi/mappers/dotnet.py
@@ -13,6 +13,37 @@ from sphinx.errors import ExtensionError
 from .base import PythonMapperBase, SphinxMapperBase
 
 
+# Doc comment patterns
+DOC_COMMENT_PATTERN = r'''
+    \<%(tag)s
+    \s+%(attr)s="(?P<attr_value>[^"]*?)"
+    \s*?
+    (?:
+        \/\>|
+        \>(?P<inner>[^\<]*?)\<\/%(tag)s\>
+    )
+'''
+DOC_COMMENT_SEE_PATTERN = re.compile(
+    DOC_COMMENT_PATTERN % {'tag': '(?:see|seealso)',
+                           'attr': 'cref'},
+    re.X)
+DOC_COMMENT_PARAM_PATTERN = re.compile(
+    DOC_COMMENT_PATTERN % {'tag': '(?:paramref|typeparamref)',
+                           'attr': 'name'},
+    re.X)
+
+# Comment member identities
+# From: https://msdn.microsoft.com/en-us/library/vstudio/fsbx0t7x(v=VS.100).aspx
+DOC_COMMENT_IDENTITIES = {
+    'N': 'ns',
+    'T': 'ref',  # can be any type (class, delegate, enum, etc), so use ref
+    'F': 'field',
+    'P': 'prop',
+    'M': 'meth',
+    'E': 'event',
+}
+
+
 class DotNetSphinxMapper(SphinxMapperBase):
 
     '''Auto API domain handler for .NET
@@ -211,25 +242,6 @@ class DotNetPythonMapper(PythonMapperBase):
 
     language = 'dotnet'
 
-    # Doc comment patterns
-    doc_comment_pattern = r'''
-        \<%(tag)s
-        \s+%(attr)s="(?P<attr_value>[^"]*?)"
-        \s*?
-        (?:
-            \/\>|
-            \>(?P<inner>[^\<]*?)\<\/%(tag)s\>
-        )
-    '''
-    doc_comment_see_pattern = re.compile(
-        doc_comment_pattern % {'tag': '(?:see|seealso)',
-                               'attr': 'cref'},
-        re.X)
-    doc_comment_param_pattern = re.compile(
-        doc_comment_pattern % {'tag': '(?:paramref|typeparamref)',
-                               'attr': 'name'},
-        re.X)
-
     def __init__(self, obj, **kwargs):
         super(DotNetPythonMapper, self).__init__(obj, **kwargs)
 
@@ -362,9 +374,29 @@ class DotNetPythonMapper(PythonMapperBase):
                 Reference on XML documentation comment syntax
         """
         try:
-            text = DotNetPythonMapper.doc_comment_see_pattern.sub(
-                ':dn:ref:`\g<attr_value>`', text)
-            text = DotNetPythonMapper.doc_comment_param_pattern.sub(
+            while True:
+                found = DOC_COMMENT_SEE_PATTERN.search(text)
+                if found is None:
+                    break
+                ref = found.group('attr_value')
+                reftype = 'ref'
+                replacement = ''
+                # Given the pattern of `\w:\w+`, inspect first letter of
+                # reference for identity type
+                if ref[1] == ':' and ref[0] in DOC_COMMENT_IDENTITIES:
+                    reftype = DOC_COMMENT_IDENTITIES[ref[:1]]
+                    ref = ref[2:]
+                    replacement = ':dn:{reftype}:`{ref}`'.format(
+                        reftype=reftype, ref=ref)
+                elif ref[:2] == '!:':
+                    replacement = ref[2:]
+                else:
+                    replacement = ':dn:ref:`{ref}`'.format(ref=ref)
+
+                text = ''.join([text[:found.start()],
+                                replacement,
+                                text[found.end():]])
+            text = DOC_COMMENT_PARAM_PATTERN.sub(
                 '``\g<attr_value>``', text)
         except TypeError:
             pass
diff --git a/tests/test_domains.py b/tests/test_domains.py
index 711a37f..dd299ad 100644
--- a/tests/test_domains.py
+++ b/tests/test_domains.py
@@ -98,12 +98,16 @@ class DomainTests(unittest.TestCase):
         self.assertEqual(ret, 'This is an example comment :dn:ref:`FOO`')
 
         ret = dotnet.DotNetPythonMapper.transform_doc_comments(
-            'This is an example comment <see cref="FOO">inner foo</see>')
-        self.assertEqual(ret, 'This is an example comment :dn:ref:`FOO`')
+            'This is an example comment <see cref="!:FOO" />')
+        self.assertEqual(ret, 'This is an example comment FOO')
 
         ret = dotnet.DotNetPythonMapper.transform_doc_comments(
-            'Test <see cref="FOO" /> and <see cref="BAR">Blah</see>')
-        self.assertEqual(ret, 'Test :dn:ref:`FOO` and :dn:ref:`BAR`')
+            'This is an example comment <see cref="N:FOO">inner foo</see>')
+        self.assertEqual(ret, 'This is an example comment :dn:ns:`FOO`')
+
+        ret = dotnet.DotNetPythonMapper.transform_doc_comments(
+            'Test <see cref="P:FOO" /> and <see cref="E:BAR">Blah</see>')
+        self.assertEqual(ret, 'Test :dn:prop:`FOO` and :dn:event:`BAR`')
 
         ret = dotnet.DotNetPythonMapper.transform_doc_comments(
             'This is an example comment <paramref name="FOO" />')