missing_doc_comment_openai

missing_doc_comment_openai

⚠️ DO NOT RUN THIS LINT ON PRIVATE SOURCE CODE ⚠️

What it does

Checks for functions missing doc comments.

Why is this bad?

Understanding what a function does is easier given a description of the function rather than just its code.

Known problems

The lint is currently enabled only for functions.

Example

pub fn foo() {}

Use instead:

/// A doc comment generated by OpenAI.
pub fn foo() {}

OpenAI

If the environment variable OPENAI_API_KEY is set to an OpenAI API key, the lint will suggest a doc comment generated by OpenAI. The prompt sent to OpenAI has the following form:

```rust
<function declaration>
```
An elaborate, high quality rustdoc comment for the above function:
```rust

The prompt's stop parameter is set to ["\n```"]. Thus, OpenAI should stop generating tokens once the second code block is complete. The suggested doc comment is the one that appears in that code block, if any.

The phrase "An elaborate..." is configurable (see below).

Configuration

Certain OpenAI parameters can be configured by setting them in the missing_doc_comment_openai table of the linted workspace's dylint.toml file. Example:

[missing_doc_comment_openai]
prompt = "A rustdoc comment for the above function with a \"Motivation\" section:"
temperature = 1.0

The following parameters are supported:

• prompt (default "An elaborate, high quality rustdoc comment for the above function:"). This default is based on OpenAI's Write a Python docstring example.
• model (default "code-davinci-002")
• temperature (default 0.2). Note that this default is less than OpenAI's default (1.0). Per the temperature documentation, "Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic."
• top_p (default none, i.e., use OpenAI's default)
• presence_penalty (default none, i.e., use OpenAI's default)
• frequency_penalty (default none, i.e., use OpenAI's default)