markdown_javadoc_references 0.1__tar.gz

markdown_javadoc_references-0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nick Hensel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

markdown_javadoc_references-0.1/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: markdown_javadoc_references
+Version: 0.1
+Summary: 
+License-File: LICENSE
+Author: Nick Hensel
+Requires-Python: >=3.9
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: beautifulsoup4
+Requires-Dist: markdown
+Requires-Dist: requests
+Description-Content-Type: text/markdown
+
+# 🐍 Python Markdown Javadoc References
+Have you ever been tired of copying entire Javadoc URLs into your Markdown just to link to the documentation for some Java classes?
+That is where is extension comes in handy! 
+
+This [python markdown extension](https://github.com/Python-Markdown/markdown) adds the ability to directly reference [Java](https://www.java.com/de/) classes, methods and fields in 
+your markdown to link to their documentation. It supports both Javadoc prior to Java 9 and from Java 9 onwards.
+
+## Installation
+You can find the [extension on PyPi](https://pypi.org/project/markdown_javadoc_references/) under `markdown_javadoc_references`.
+
+### With plain [python markdown](https://github.com/jackdewinter/pymarkdown)
+To use this extension with the API of [python markdown](https://github.com/jackdewinter/pymarkdown), just add
+`JavaDocRefExtension` to the list of your extensions and provide the URLs to use.
+
+```python
+import markdown
+from markdown_javadoc_references import JavaDocRefExtension
+
+urls = [
+    'https://docs.oracle.com/en/java/javase/24/docs/api/',
+    {
+        'alias': 'jdk8',
+        'url': 'https://docs.oracle.com/javase/8/docs/api/'
+    }
+]
+
+text = 'your markdown text'
+result = markdown.markdown(text, extensions=[JavaDocRefExtension(urls=urls)])
+```
+
+
+### With [MkDocs](https://www.mkdocs.org/)
+To use this extension with [MkDocs](https://www.mkdocs.org/) just add it to your `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - markdown_javadoc_references:
+      - urls:
+          - 'https://docs.oracle.com/en/java/javase/24/docs/api/'
+          - alias: 'jdk8'
+            url: 'https://docs.oracle.com/javase/8/docs/api/'
+```
+
+## Usage
+Referencing java methods, classes or fields is similar to how it is done in normal javadoc comments, for example
+`[String#concat(String)](String#concat(String))` will result in [String#concat(String)](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#concat(java.lang.String))
+
+### Autolinks
+Often times the text presented to the user is the same as the javadoc reference.
+For this common case you can use the autolink syntax to avoid writing it twice.
+
+`<String#concat(String)>` is the same as `[String#concat(String)](String#concat(String))`
+
+### Packages
+To clarify which class to use, you can add a package in front of it:
+`<java.lang.String>`.
+
+Furthermore, you can also a package to method parameters:
+`<String#concact(java.lang.String)`
+
+> [!WARNING]
+> If multiple matches are found for a reference, the reference will be marked as "Invalid"!
+
+### Fields
+Like methods, fields can be referred to in a similar style with the small detail of double `#`: `<String##CASE_INSENSITIVE_ORDER>` will link to [String#CASE_INSENSITIVE_ORDER](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#CASE_INSENSITIVE_ORDER)
+
+The double `#` is necessary to avoid conflicts with markdowns native headline linking.
+
+### Constructors
+To refer to constructors, just add `<init>` in the place where the method name would be:
+`String#<init>(byte[],int,int)` will link to [String#<init>(byte[],int,int)](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#%3Cinit%3E(byte%5B%5D,int,int))
+
+### URL aliases
+Instead of stating the package explicitly, you can also add a URL alias to your reference.
+For that to work, you have to state the alias for your javadoc site in your [configuration. (take a look at installation)](#installation)
+
+Assuming you have a javadoc site configured with the alias "jdk8":
+```yaml
+markdown_extensions:
+  - markdown_javadoc_references:
+      - urls:
+        - 'https://docs.oracle.com/en/java/javase/24/docs/api/'
+        - alias: 'jdk8'
+          url: 'https://docs.oracle.com/javase/8/docs/api/'
+```
+
+you can now use this alias to force the extension to only search under the site `https://docs.oracle.com/javase/8/docs/api/`
+for the referred to javadoc: `<jdk8 -> String#<init>(byte[],int,int)>` 
+
+Additionally, if you don't have an alias configured explicitly, you can still use the whole URL:
+`<https://docs.oracle.com/en/java/javase/24/docs/api/ -> String#<init>(byte[],int,int)>`
+
+> [!IMPORTANT]
+> The URL has to be still mentioned in the configuration!

markdown_javadoc_references-0.1/README.md

@@ -0,0 +1,94 @@
+# 🐍 Python Markdown Javadoc References
+Have you ever been tired of copying entire Javadoc URLs into your Markdown just to link to the documentation for some Java classes?
+That is where is extension comes in handy! 
+
+This [python markdown extension](https://github.com/Python-Markdown/markdown) adds the ability to directly reference [Java](https://www.java.com/de/) classes, methods and fields in 
+your markdown to link to their documentation. It supports both Javadoc prior to Java 9 and from Java 9 onwards.
+
+## Installation
+You can find the [extension on PyPi](https://pypi.org/project/markdown_javadoc_references/) under `markdown_javadoc_references`.
+
+### With plain [python markdown](https://github.com/jackdewinter/pymarkdown)
+To use this extension with the API of [python markdown](https://github.com/jackdewinter/pymarkdown), just add
+`JavaDocRefExtension` to the list of your extensions and provide the URLs to use.
+
+```python
+import markdown
+from markdown_javadoc_references import JavaDocRefExtension
+
+urls = [
+    'https://docs.oracle.com/en/java/javase/24/docs/api/',
+    {
+        'alias': 'jdk8',
+        'url': 'https://docs.oracle.com/javase/8/docs/api/'
+    }
+]
+
+text = 'your markdown text'
+result = markdown.markdown(text, extensions=[JavaDocRefExtension(urls=urls)])
+```
+
+
+### With [MkDocs](https://www.mkdocs.org/)
+To use this extension with [MkDocs](https://www.mkdocs.org/) just add it to your `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - markdown_javadoc_references:
+      - urls:
+          - 'https://docs.oracle.com/en/java/javase/24/docs/api/'
+          - alias: 'jdk8'
+            url: 'https://docs.oracle.com/javase/8/docs/api/'
+```
+
+## Usage
+Referencing java methods, classes or fields is similar to how it is done in normal javadoc comments, for example
+`[String#concat(String)](String#concat(String))` will result in [String#concat(String)](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#concat(java.lang.String))
+
+### Autolinks
+Often times the text presented to the user is the same as the javadoc reference.
+For this common case you can use the autolink syntax to avoid writing it twice.
+
+`<String#concat(String)>` is the same as `[String#concat(String)](String#concat(String))`
+
+### Packages
+To clarify which class to use, you can add a package in front of it:
+`<java.lang.String>`.
+
+Furthermore, you can also a package to method parameters:
+`<String#concact(java.lang.String)`
+
+> [!WARNING]
+> If multiple matches are found for a reference, the reference will be marked as "Invalid"!
+
+### Fields
+Like methods, fields can be referred to in a similar style with the small detail of double `#`: `<String##CASE_INSENSITIVE_ORDER>` will link to [String#CASE_INSENSITIVE_ORDER](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#CASE_INSENSITIVE_ORDER)
+
+The double `#` is necessary to avoid conflicts with markdowns native headline linking.
+
+### Constructors
+To refer to constructors, just add `<init>` in the place where the method name would be:
+`String#<init>(byte[],int,int)` will link to [String#<init>(byte[],int,int)](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/String.html#%3Cinit%3E(byte%5B%5D,int,int))
+
+### URL aliases
+Instead of stating the package explicitly, you can also add a URL alias to your reference.
+For that to work, you have to state the alias for your javadoc site in your [configuration. (take a look at installation)](#installation)
+
+Assuming you have a javadoc site configured with the alias "jdk8":
+```yaml
+markdown_extensions:
+  - markdown_javadoc_references:
+      - urls:
+        - 'https://docs.oracle.com/en/java/javase/24/docs/api/'
+        - alias: 'jdk8'
+          url: 'https://docs.oracle.com/javase/8/docs/api/'
+```
+
+you can now use this alias to force the extension to only search under the site `https://docs.oracle.com/javase/8/docs/api/`
+for the referred to javadoc: `<jdk8 -> String#<init>(byte[],int,int)>` 
+
+Additionally, if you don't have an alias configured explicitly, you can still use the whole URL:
+`<https://docs.oracle.com/en/java/javase/24/docs/api/ -> String#<init>(byte[],int,int)>`
+
+> [!IMPORTANT]
+> The URL has to be still mentioned in the configuration!

markdown_javadoc_references-0.1/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "markdown_javadoc_references"
+version = "0.1"
+
+dependencies = [
+    "requests",
+    "markdown",
+    "beautifulsoup4"
+]
+
+authors = [
+    {name = "Nick Hensel"}
+]
+readme = "README.md"
+requires-python = ">=3.9"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest-xdist (>=3.8.0,<4.0.0)",
+    "pytest (>=8.4.2,<9.0.0)"
+]

markdown_javadoc_references-0.1/src/markdown_javadoc_references/__init__.py

@@ -0,0 +1,6 @@
+from .extension import JavaDocRefExtension
+
+__all__ = ["JavaDocRefExtension"]
+
+def makeExtension(**kwargs):
+    return JavaDocRefExtension(**kwargs)

markdown_javadoc_references-0.1/src/markdown_javadoc_references/docsite/docsite.py

@@ -0,0 +1,12 @@
+from functools import lru_cache
+
+from .jdk8 import load as jdk8_load
+from .jdk9 import load as jdk9_load
+from .util import check_url
+
+
+@lru_cache(maxsize=None)
+def load(url):
+    # /allclasses-noframe.html only exists pre java 9
+    existing = check_url(f'{url}/allclasses-noframe.html')
+    return jdk8_load(url) if existing else jdk9_load(url)

markdown_javadoc_references-0.1/src/markdown_javadoc_references/docsite/jdk8.py

@@ -0,0 +1,93 @@
+import logging
+import urllib.parse
+from concurrent.futures import ThreadPoolExecutor
+
+from bs4 import BeautifulSoup
+
+from .util import read_url
+from ..entities import *
+
+logger = logging.getLogger(__name__)
+
+
+def load(url):
+    # info is intended
+    logger.info(f'Loading java 8 docs.. may take a while: {url}')
+
+    soup = BeautifulSoup(read_url(f'{url}/allclasses-noframe.html'), 'html.parser')
+
+    klasses = dict()
+
+    for anchor in soup.find('body').find('div').find('ul').select('a[href]'):
+        klass = load_class(url, anchor)
+        klasses.setdefault(klass.name, []).append(klass)
+
+    return Jdk8(klasses)
+
+
+def load_class(url, c):
+    name = c.get_text(strip=True)
+    package = c.get('title').split()[-1]
+
+    klass = Klass(None, package, name, None, None, f'{url}/{c.get('href')}')
+    logger.info(f'Loading {package}.{name} from {klass.url}')
+
+    return klass
+
+
+def load_members(url, klass):
+    text = read_url(url)
+    klass.methods = list()
+    klass.fields = list()
+
+    soup = BeautifulSoup(text, "html.parser")
+    anchors = {a.get("name") for a in soup.find_all("a", attrs={"name": True})}
+    for a in anchors:
+        parts = a.split('-')
+        unquoted_url = urllib.parse.unquote(f'{url}#{a}')
+        # first part is always name
+        member_name = parts[0]
+
+        # is field
+        if len(parts) <= 1:
+            klass.fields.append(Field(member_name, unquoted_url))
+
+        if member_name == klass.name: member_name = '<init>' # normalize constructor method names to <init>
+        new_params = []
+
+        # following parts are parameters
+        for param in parts[1:]:
+
+            # skip empty strings - they're not real parameters
+            if len(param) == 0: continue
+
+            # split at : - after it there are metadata like A for arrays
+            name_split = param.split(':')
+            new_name = name_split[0]
+
+            # add [] for arrays
+            if len(name_split) == 2:
+                new_name = new_name + ('[]' * (name_split[1].count('A')))
+
+            new_params.append(new_name.strip())
+
+
+        klass.methods.append(Method(klass, member_name, new_params, unquoted_url))
+
+class Jdk8:
+    def __init__(self, klasses):
+        self.klasses = klasses
+
+    # lazy load
+    def klasses_for_ref(self, reference):
+        if reference.class_name not in self.klasses: return None
+        found = self.klasses[reference.class_name]
+
+        loaded = list()
+        for klass in found:
+            # none if unloaded
+            if klass.methods is None:
+                load_members(klass.url, klass)
+            loaded.append(klass)
+
+        return loaded

markdown_javadoc_references-0.1/src/markdown_javadoc_references/docsite/jdk9.py

@@ -0,0 +1,117 @@
+import json
+import logging
+import urllib.parse
+
+from .util import read_url
+from ..entities import *
+
+logger = logging.getLogger(__name__)
+
+
+def load(url):
+    logger.debug(f'Load java 9 doc: {url}')
+
+    packages = load_packages(url)
+    members = load_members(url)
+
+    klasses =  load_classes(url, packages, members)
+    return Jdk9(klasses)
+
+
+def read_url_json(url, prefix):
+    text = read_url(url)
+    plain = text.removeprefix(prefix).removesuffix(';updateSearchResults();').strip()
+    return json.loads(plain)
+
+
+def find_module(name, pkgs):
+    e = pkgs[name]
+    if 'm' in e:
+        return e['m']
+    return None
+
+
+def load_members(url):
+    data = read_url_json(url + '/member-search-index.js', 'memberSearchIndex = ')
+
+    index = dict()
+    for e in data:
+        if 'l' not in e or 'p' not in e: continue
+        index.setdefault(f'{e['p']}.{e['c']}', list()).append(e)
+    return index
+
+
+def load_classes(url, pkgs, members):
+    data = read_url_json(url + '/type-search-index.js', 'typeSearchIndex = ')
+    klasses = dict()
+
+    for e in data:
+        # skip non member entries
+        if 'l' not in e or 'p' not in e: continue
+        name = e['l']
+        package = e['p']
+        module = find_module(package, pkgs)
+        methods = list()
+        fields = list()
+
+        klass_url = build_klass_url(url, module, package, name)
+        klass = Klass(module, package, name, methods, fields, klass_url)
+
+        i = f'{package}.{name}'
+
+        # check if class has members
+        if i in members:
+
+            # get through all members of class
+            for m in members[i]:
+                # u in only included if reference types are parameters. No parameters + only primitives -> l
+                index = 'u' if 'u' in m else 'l'
+                m_name = urllib.parse.unquote(m[index].split('(', 1)[0])  ## get name -> split at ( and get first half
+                parameters = list()
+
+                raw = m[index]
+                if '(' in raw:  # just exclude fields for now
+                    u_split = raw.split('(', 1)[1].removesuffix(')')
+                    if len(u_split) != 0:
+                        for p in u_split.split(','):
+                            parameters.append(p.strip())
+                    methods.append(Method(klass, m_name, parameters, build_method_url(klass_url, m)))
+                else: # is field
+                    fields.append(Field(m_name, build_field_url(klass_url, m_name)))
+
+        klasses.setdefault(name, list()).append(klass)
+
+    return klasses
+
+
+def build_klass_url(base, module, package, klass_name):
+    # append module name if given
+    if module is not None: base = f'{base}/{module}'
+    # append package name
+    base = f'{base}/{package.replace('.', '/')}'
+    # append class name
+    base = f'{base}/{klass_name}'
+
+    # append .html
+    return base + '.html'
+
+def build_method_url(klass_url, m):
+    return f'{klass_url}#{(m['u'] if 'u' in m else m['l'])}'
+
+def build_field_url(klass_url, field_name):
+    return f'{klass_url}#{field_name}'
+
+def load_packages(url):
+    data = read_url_json(url + '/package-search-index.js', 'packageSearchIndex = ')
+
+    index = dict()
+    for e in data:
+        index[e['l']] = e
+    return index
+
+class Jdk9:
+    def __init__(self, klasses):
+        self.klasses = klasses
+
+    def klasses_for_ref(self, reference):
+        return self.klasses[reference.class_name] if reference.class_name in self.klasses else None

markdown_javadoc_references-0.1/src/markdown_javadoc_references/docsite/util.py

@@ -0,0 +1,12 @@
+import requests
+
+
+def read_url(url):
+    resp = requests.get(url)
+    resp.raise_for_status()
+    return resp.text
+
+
+def check_url(url):
+    resp = requests.head(url)
+    return resp.ok

markdown_javadoc_references-0.1/src/markdown_javadoc_references/entities.py

@@ -0,0 +1,20 @@
+class Klass:
+    def __init__(self, module, package, name, methods, fields, url):
+        self.module = module
+        self.package = package
+        self.name = name
+        self.methods = methods
+        self.url = url
+        self.fields = fields
+
+class Field:
+    def __init__(self, name, url):
+        self.name = name
+        self.url = url
+
+class Method:
+    def __init__(self, klass, name, parameters, url):
+        self.klass = klass
+        self.name = name
+        self.parameters = parameters
+        self.url = url

markdown_javadoc_references-0.1/src/markdown_javadoc_references/extension.py

@@ -0,0 +1,17 @@
+from markdown.extensions import Extension
+
+from .processor import JavaDocProcessor, AutoLinkJavaDocProcessor
+
+
+class JavaDocRefExtension(Extension):
+    def __init__(self, **kwargs):
+        self.config = {
+            'urls': [[], 'A list of javadoc sites to search in.']
+        }
+
+        super().__init__(**kwargs)
+
+    def extendMarkdown(self, md):
+        md.treeprocessors.register(JavaDocProcessor(md, self.getConfig("urls")), 'javadoc_reference_processor', 15)
+
+        md.inlinePatterns.register(AutoLinkJavaDocProcessor(md), 'javadoc_reference_autolink_processor', 140)

markdown_javadoc_references-0.1/src/markdown_javadoc_references/processor.py

@@ -0,0 +1,120 @@
+import logging
+from concurrent.futures import ThreadPoolExecutor
+import xml.etree.ElementTree as etree
+
+from markdown.treeprocessors import Treeprocessor
+from markdown.inlinepatterns import InlineProcessor
+
+from .docsite import docsite
+from .reference import create_or_none
+from .reference import Type
+
+from .reference import raw_pattern as ref_pattern
+
+logger = logging.getLogger(__name__)
+
+
+def match(klasses, reference):
+    # search in each class
+    for klass in klasses:
+        # compare package if given
+        if reference.package is not None and (klass.package != reference.package): continue
+        # compare method if given
+        if reference.member_name is not None:
+            if reference.type == Type.METHOD:
+                # get all methods for class
+                methods = klass.methods
+                # search in each member
+                for method in methods:
+                    # compare method name
+                    if reference.member_name != method.name: continue
+                    # compare parameter size
+                    if len(reference.parameters) != len(method.parameters): continue
+
+                    # compare parameters
+                    parameter_match = True
+                    for r_p, m_p in zip(reference.parameters, method.parameters):
+                        if not m_p.endswith(r_p): parameter_match = False
+                    if not parameter_match: continue
+
+                    return method.url
+            else:
+                # get all fields
+                fields = klass.fields
+
+                # compare each field
+                for field in fields:
+                    if reference.member_name != field.name: continue
+                    return field.url
+
+        else:  # if not given, just reference found class
+            return klass.url
+
+    return None
+
+def process_url(url):
+    stripped_url = url.removesuffix('/')
+    return docsite.load(stripped_url)
+
+class JavaDocProcessor(Treeprocessor):
+    def __init__(self, md, urls):
+        super().__init__(md)
+        self.sites = dict()
+
+        for entry in urls:
+            if isinstance(entry, str):
+                site = process_url(entry)
+                self.sites[entry.strip()] = site
+            elif isinstance(entry, dict) and 'alias' in entry and 'url' in entry:
+                site = process_url(entry['url'])
+                self.sites[entry['alias'].strip()] = site
+            else:
+                raise TypeError(
+                    f"Invalid entry in urls config: {entry!r}. "
+                    f"Expected string or dict with 'alias' and 'url'."
+                )
+
+
+    def run(self, root):
+        for el in root.iter('a'):
+            href = el.get('href', '')
+            reference = create_or_none(href)
+            if reference is not None:
+                links = self.find_matching_javadoc(reference)
+
+                if len(links) == 0:
+                    logger.warning(f'No javadoc matching {href} was found!')
+                    el.text = f'Invalid reference to {href}'
+                elif len(links) > 1:
+                    logger.warning(
+                        f'Multiple javadoc matching {href} found! Please be more specific, maybe add a pacakge? Found javadocs: {'; '.join(links)}')
+                    el.text = f'Invalid reference to {href}'
+                else:
+                    url = links[0]
+                    el.set('href', url)
+
+    def find_matching_javadoc(self, reference):
+        matches = list()
+        for alias, site in self.sites.items():
+            if reference.javadoc_alias is not None:
+                if alias != reference.javadoc_alias: continue
+
+            klasses = site.klasses_for_ref(reference)
+            if klasses is None: continue
+            link = match(klasses, reference)
+            if link is not None: matches.append(link)
+        return matches
+
+
+auto_link_pattern = rf'<({ref_pattern[:-1]})>$'
+class AutoLinkJavaDocProcessor(InlineProcessor):
+    def __init__(self, md):
+        super().__init__(auto_link_pattern, md)
+
+    def handleMatch(self, m, data):
+        text = m.group(1)
+        el = etree.Element('a')
+        el.set('href', text)
+        # replace ## with # - ## is used for field referring
+        el.text = m.group('whole_ref').replace('##', '#')
+        return el, m.start(0), m.end(0)

markdown_javadoc_references-0.1/src/markdown_javadoc_references/reference.py

@@ -0,0 +1,53 @@
+from enum import Enum
+
+import re
+
+raw_pattern = r'(?:(?P<doc>.+) *-> *)?(?P<whole_ref>(?P<pkg>[\w.]*\.)?(?P<klass>\w+)(?:#(?:(?P<method><?\w+>?)\((?P<params>.*)\))|(?:##(?P<field>\w+)))?)$'
+pattern = re.compile(raw_pattern)
+
+def create_or_none(raw):
+    match = pattern.match(raw)
+    return Reference(match) if match else None
+
+
+class Reference:
+    def __init__(self, match: re.Match):
+        """
+        regex will match: alias -> java.util.com.MyClass#foo(String,int,boolean) -->
+
+        group doc: javadoc alias name
+        group pkg: package (optional)
+        group klass: class name
+        group method: method name (optional, together with parameters)
+        group params: parameters (optional, together with method name)
+
+        if field reference: java.util.com.MyClass#MY_FIELD
+        group field: field name
+        """
+
+        self.javadoc_alias = match.group('doc')
+        if self.javadoc_alias is not None:
+            self.javadoc_alias = self.javadoc_alias.strip()
+
+        self.package = match.group('pkg')
+        if self.package is not None: self.package = self.package.removesuffix('.')
+
+        self.class_name = match.group('klass')
+
+        if match.group('field') is None:
+            self.member_name = match.group('method')
+
+            self.parameters = list()
+
+            parameter = match.group('params')
+            if parameter is not None and parameter != '':
+                for par in parameter.split(','):
+                    self.parameters.append(par.strip())
+            self.type = Type.METHOD
+        else:
+            self.type = Type.FIELD
+            self.member_name = match.group('field')
+
+class Type(Enum):
+    METHOD = 1
+    FIELD = 2