DEV Community

loading...

How to write Godoc?

patarapolw profile image Pacharapol Withayasakpunt ・1 min read

These pretty much says it.

In short, starting with a sentence with Function name as first noun. Markdown might also be supported. (At least for hyperlinks, and)

    // to `nil` or the value to `""` to use the default generated endpoint.
    //
    // Note: You must still provide a `Region` value when specifying an
Enter fullscreen mode Exit fullscreen mode

Nothing near the level of JSDoc, JavaDoc, or several of Python docstring conventions, though; where Arguments and Returns, as well as Errors, are documented. Also, syntax highlighting for JSDoc/JavaDoc are far superior (with @annotation).

Discussion

pic
Editor guide
Collapse
delta456 profile image
Collapse
patarapolw profile image
Pacharapol Withayasakpunt Author

Thanks for official guide, but of course, I did come from other languages first (like Python, JavaScript, Java).

I am also looking for Doctest (originally in Python, and may be adaptable in some other languages.) - reddit.com/r/golang/comments/bafug...

For references,

Python "Google style" docstring.

def checksum(data: Union[str, bytes]) -> str:
    """[summary]

    Args:
        data (Union[str, bytes]): [description]

    Returns:
        str: [description]
    """
    if isinstance(data, str):
        data = data.encode("utf-8")
    return sha1(data).hexdigest()
Enter fullscreen mode Exit fullscreen mode
def ankiconnect(action: str, **params):
    """[summary]

    Args:
        action (str): [description]

    Raises:
        Exception: [description]
        Exception: [description]
        Exception: [description]
        Exception: [description]

    Returns:
        [type]: [description]
    """
Enter fullscreen mode Exit fullscreen mode

JavaScript JSDoc / TypeScript TSDoc (which is almost similar to JavaDoc).

TSDoc

Again, I am looking to write Documentations that don't lose any information I wanted, not really that "Just following recommendations".

Let me complain this again...