Using GitHub Copilot for Documentation: Comments and User Guides
GitHub Copilot · Learning with GitHub Copilot · By Super Admin
GitHub Copilot can assist developers with documentation tasks such as writing code comments and generating user guides like API documentation.
Documentation is often a task developers dread, partly because of the perception that well-written code should be self-explanatory, and partly because of the trade-off between the value of creating code versus writing documentation. Despite this, documentation is often a critical part of successful software development, and GitHub Copilot can assist in various parts of the process, such as with comments, pull request descriptions, and user guides. A pull request is when you merge code changes into the code from one branch to another, which is done in a version control system like GitHub.
Comments
Writing comments in your code can help with the learning process and knowledge sharing, meaning your team will not have to spend as much time understanding what you have created. However, writing comments can be tedious, and in some cases they may not necessarily be easy to understand. GitHub Copilot can help generate these comments directly in the editor. For example, you can open Copilot Chat in VS Code and use a prompt such as: "Write a function, called reverse_string, that takes a string as an input and returns the string reversed. Write comments that explain each of the key steps of this program." Copilot responds by inserting comments but also provides a docstring, which is used as the first statement in a Python function to describe it.
Figure: Screenshot of Python reverse string function with its docstring and 2 commented steps for implementation.
As AI coding becomes more common, the use of comments may actually start to fade. The reason is that if a developer does not understand a code snippet, they can have the AI coding tool easily provide an explanation instead of relying on written comments.
User Guides
Using GitHub Copilot to write a user guide is similar to the process for creating comments. To generate documentation for an API, you can open Copilot Chat in VS Code and use a prompt such as: "Generate API documentation for this REST endpoint. Write this in Markdown format." Copilot responds with API documentation that includes details about the endpoints and even provides code examples.
Figure: Screenshot of A P I documentation with base U R L localhost, port 3000, and GET endpoint returning a welcome message.
This shows how the same chat-based workflow used for generating comments can be applied to producing more extensive documentation, such as API references, in Markdown format.
Key takeaways
- Documentation, though often dreaded, is a critical part of successful software development, and GitHub can assist with comments, pull request descriptions, and user guides.
- Copilot Chat can generate code comments and docstrings, such as for a reverse_string function, reducing the tedium of writing comments manually.
- As AI coding tools become more common, reliance on written comments may fade since developers can ask the AI to explain unclear code directly.
- Copilot Chat can also generate user documentation, such as API documentation in Markdown format, including endpoint details and code examples.
Discussion (0)
No discussion on this article yet — be the first to comment.
Please sign in to join the discussion.