|
| 1 | +--- |
| 2 | +name: adk-unit-guide |
| 3 | +description: Creates detailed code unit guides for source code documentation. |
| 4 | +--- |
| 5 | + |
| 6 | +# ADK code unit guide |
| 7 | +This skill creates a detailed developer guide for new or updated code file or direct code input. The guide it generates is meant to explain the code to a developer who wants to use it in an application, but with a higher level of technical detail than what would appear in published developer documentation. Similar to a *unit test*, a *unit guide* provides generated, granular-level documentation for a unit of code, without worrying about bloating the actual developer documentation with too many details. |
| 8 | + |
| 9 | +## Input |
| 10 | + |
| 11 | +- Code files containing new functionality |
| 12 | +- Code unit tests (optional) |
| 13 | +- Code design files (optional) |
| 14 | +- Names of new methods and classes (optional) |
| 15 | + |
| 16 | +## Analysis |
| 17 | + |
| 18 | +- Review the code design files, if provided. Make note of: |
| 19 | + - Purpose and intended use of the new or updated code units |
| 20 | + - Classes that depend on the new or updated code units |
| 21 | + - Additional dependencies required by the new or updated code units |
| 22 | + - Limitations of the new or updated code units |
| 23 | +- Review specified code file for changes and named methods, if provided. |
| 24 | +- Determine what classes and code files may depend on the new or updated code units. |
| 25 | + |
| 26 | +## Output |
| 27 | + |
| 28 | +- Look for an existing guide in the `/docs/guides/***` directory of this repository. |
| 29 | + - If a guide already exists, update the existing guide incrementally and prioritize preserving the previous content as much as possible. |
| 30 | + - If no guide exists, create a guide file for the new code unit in the `/docs/guides/***` directory of this repository, using the relative path of the code unit. For example, if the code unit is called `/topic/function/class.ext`, create a guide in the location `/docs/guides/topic/function/class/index.md`. |
| 31 | + |
| 32 | +### Guide structure and content |
| 33 | + |
| 34 | +Use the following structure and instructions to create the guide for the code unit: |
| 35 | + |
| 36 | +``` |
| 37 | +# Title: name of the code file or code unit |
| 38 | +
|
| 39 | +- 2-sentence summary of the code unit |
| 40 | +
|
| 41 | +## Introduction |
| 42 | +
|
| 43 | +- Paragraph(s) explaining: |
| 44 | + - The purpose and application of the code unit |
| 45 | + - Key classes that depend on this code unit |
| 46 | + - Developer problems solved by this code unit |
| 47 | +
|
| 48 | +## Get started |
| 49 | +
|
| 50 | +- Present a single, minimum implementation of the code unit to demonstrate its use. |
| 51 | +- Show enough of the containing classes to make it clear where the code could be used. |
| 52 | +- Use unit test code as a starting point for the code example, if available. |
| 53 | +
|
| 54 | +## How it works |
| 55 | +
|
| 56 | +- Explain how the code unit accomplishes its purpose or solves a problem. |
| 57 | +- Mention key code classes that depend on this code unit. |
| 58 | +- Mention code classes that this code unit depends on. |
| 59 | +- Explain any cross-class dependencies of the code unit. |
| 60 | +
|
| 61 | +## Configuration options |
| 62 | +
|
| 63 | +- If the code unit has configuration options, document them in a table detailing parameters, types, default values, and descriptions. |
| 64 | +
|
| 65 | +## Advanced applications |
| 66 | +
|
| 67 | +- Determine if there are advanced use cases for the code unit. |
| 68 | +- Add advanced applications of the code unit, including: |
| 69 | + - Problem solved |
| 70 | + - Implementations for special circumstances |
| 71 | +
|
| 72 | +## Limitations |
| 73 | +
|
| 74 | +- Mention any limitations of the code unit, if known. |
| 75 | +
|
| 76 | +``` |
0 commit comments