Documentation from code: how to refine generated text to exact function descriptions
The "Code Documentation" tool creates a draft description of provided functions: parameters, return values, examples and limitations. The first result almost always requires refinement because the model does not know your project context. This guide shows how to turn the generated text into accurate and useful documentation in several iterations, without adding non-existent capabilities.
Ouvrir l'outil: Rédacteur de documentation de code ↗What the tool exactly does and what input it needs
The tool accepts two fields: "Code and error message" (up to 8000 characters) and "Platform or application" (up to 1000 characters). In the first field, insert the source code of the functions you need to document. The second field specifies the environment: language, framework, version, environment specifics. On output you get one text result in a separate panel, which you can copy or download as TXT.
Important to understand: the tool does not analyze your repository, does not connect to the development environment and does not check code for execution. It works only with the text you pass. If there are non-obvious dependencies or side effects in the code, you need to describe them in the platform field or add them to code comments.
For example, for a Python function it is enough to pass its definition. But if the function uses a global variable or external API, indicate this in the platform description, otherwise the model may misinterpret the behavior.
Field "Code and error message": def add(a, b): return a + b. Field "Platform or application": Python 3.11, pure function without side effects.
First result: what usually comes out and what to check in it
After pressing "Generate" you will get structured text: function description, list of parameters with types, description of return value, usage example and limitations section. This is a good basis, but it may contain inaccuracies: the model may assign the wrong type to a parameter, add a non-existent exception or suggest an example that does not match your codebase.
Check each point. Pay special attention to limitations: the model often writes general phrases like "does not work with negative numbers" if the code does not have explicit checking. Such statements need to be confirmed or deleted. Also check that the code example is syntactically correct and uses only functions that really exist in your codebase.
Do not try to fix everything at once. First mark factual errors, then stylistic roughness. This will help formulate precise corrections for the next iteration.
The first result may contain: "Parameter a: integer". If the code has no annotations, this is an assumption, not a fact. Check against the source.
How to formulate corrections for the second iteration
The second iteration is a repeated run with refined input. You do not need to rewrite the whole code again. It is enough to add brief instructions to the "Platform or application" field: what types to use, which exceptions to mention, which examples to provide. For example: "Parameters - integers. Returns integer. Does not handle overflow. Example: add(2, 3) returns 5."
If the first result has extra sections, indicate this in the platform description: "Do not add a performance section, only parameters, return, example and limitations". The tool has no settings for choosing sections, so management is done through text request.
Formulate corrections specifically. Instead of "make better" write "replace example with a call with two arguments and expected result". The more precise the instruction, the closer the second result is to ready-to-use text.
Add to the platform field: "Types: a and b - integers. Return: integer. Limitation: does not check overflow. Example: add(2, 3) -> 5."
Checking examples and limitations for realism
Examples must be executable and correspond to the function signature. If the first result example calls a function with a different number of arguments or uses a non-existent module, this must be corrected. In the second iteration explicitly indicate the expected output: "add(2, 3) returns 5". The model does not run code, so it may err in calculations if the example is complex.
Limitations - the most vulnerable part. The model tends to invent limitations that do not exist in the code. Check every statement: really does the function not handle negative numbers? Is there a None check? If the code has no explicit handling, it is better to write "behavior with negative values is not defined" rather than asserting that the function does not accept them.
If the function returns None in some cases, this is also a limitation. Make sure it is reflected. Do not add limitations that do not follow from the code or platform description.
For def add(a, b): return a + b correct limitation: "Does not perform type checking; passing strings will result in concatenation". This follows from Python behavior.
Working with error message in input field
The "Code and error message" field allows you to pass not only code, but also error text. This is useful if the function calls an exception under certain conditions. For example, if a function divides by zero, add the message "ZeroDivisionError: division by zero". Then the model will be able to describe this exception in the limitations section.
However do not overload the field: limit 8000 characters. If the code is large, it is better to split it into several runs per function. The result will be more accurate, and checking - easier. Create a separate request for each function.
If the error does not relate to the function being documented, do not include it. The model may erroneously link the message to the wrong part of the code.
Add to the code field: "If b=0 raises ZeroDivisionError". This will help generate a correct limitation.
Final proofreading and tool limitations
After the second or third iteration you have a draft that needs manual proofreading. Check: are all parameters described, does the return value match the code, are there invented exceptions, is the example correct? The tool does not guarantee flawlessness, so final responsibility is on you.
Remember technical limitations: no DOCX or PDF export, no batch processing, no automatic saving. Result can only be copied or downloaded as TXT. Vector images (SVG, PNG) and speech (eSpeak WAV) are available, but do not relate to this task. The model may err, and queue and availability vary.
Do not use the tool to generate documentation for closed code if this violates security policy. Also do not expect it to replace manual testing or code analysis.
Final text for add(a, b): "The add function takes two integers and returns their sum. Parameters: a, b - integers. Return: integer. Example: add(2, 3) -> 5. Limitation: does not check types; passing strings performs concatenation".
Refining code documentation is an iterative process: generate a draft, check facts, refine inputs and repeat. The "Code Documentation" tool accelerates creating the foundation, but does not replace careful analysis. Following the described steps, you will get an accurate function description with realistic examples and limitations, without adding non-existent capabilities.
Ouvrir l'outil: Rédacteur de documentation de code ↗Les traductions de l'interface sont assistées par machine et peuvent nécessiter des améliorations.