Skip to content

Guided File Processing

Guided File Processing leverages AI Ghostwriter’s intelligent documentation and code guidance engine to automate, standardize, and enhance project documentation and code annotation across multi-module projects. By embedding actionable @guidance annotations, it ensures consistency, clarity, and maintainability throughout your codebase and documentation assets.

The workflow establishes a content pipeline where @guidance annotations embedded in source and test code direct the documentation system to extract, organize, and present information. This curated documentation then serves as the foundation for both the build configuration and the project’s README, ensuring consistency, accuracy, and automation across all generated project materials.

Guided file processing operates across multiple layers of your project:

  1. Documentation as the Central Hub
    The documentation folder, specifically its docs collection, acts as the central point for content generation. It gathers information from both the source (code) and test (code) collections.
  2. Functional Information: The documentation extracts functional details from the source code, often guided by @guidance annotations within the codebase. These annotations help identify what aspects of the code should be documented or highlighted.

  3. Usage Information: The documentation also pulls in usage examples and test scenarios from the test code, again leveraging @guidance annotations to determine which tests or usage patterns are relevant for inclusion.

  4. Build File Integration
    The project’s Build File utilizes data from the documentation (docs) to inform the build process.

  5. This may include generating build metadata, assembling documentation artifacts, or configuring build steps based on @guidance-driven documentation content.

  6. README Generation
    The README file is generated or enriched using descriptive content from the documentation (docs).

  7. @guidance annotations within the documentation help ensure that the README includes up-to-date project descriptions, module overviews, and usage instructions, all derived from the most relevant and authoritative sources.

Guidance Annotations

Special @guidance annotations deliver actionable instructions and best practices directly within your project files. These annotations are clear, non-intrusive, and easy to follow for both humans and automated tools.

Folder Level Guidance

File name: @guidance.txt

Place this file in the root directory (and submodules as needed) to provide essential instructions for maintaining project structure and documentation standards.

In the project root directory, ensure the following files are present and properly created:

**LICENSE.txt**
   - Include the full text of the project's license.
   - If the license file is missing, create it using the license type defined in the pom.xml file.
   - Ensure the license terms are accurate and up to date.

**README.md**
   - Generate a standard `README.md` file for a multi-module Java project managed in a Git repository.

README Content:

1. **Project Title and Overview:**  
   - Provide the project name and a brief description of its purpose and main features.

2. **Module List:**  
   - List all modules in the project.
   - For each module, include its name, a short description, and a link to its subdirectory.

3. **Installation Instructions:**  
   - Describe how to clone the repository and build the project (e.g., using Maven or Gradle).
   - Include prerequisites such as Java version and build tools.

4. **Usage:**  
   - Explain how to run or use the project and its modules.
   - Provide example commands or code snippets if applicable.

5. **Contributing:**  
   - Outline guidelines for contributing to the project, including code style, pull request process, and issue reporting.

6. **License:**  
   - State the project’s license and provide a link to the license file.

7. **Contact and Support:**  
   - Include contact information or links for support and further questions.

**Formatting Requirements:**
- Use Markdown syntax for headings, lists, code blocks, and links.
- Ensure clarity and conciseness in each section.
- Organize the README for easy navigation and readability.

Markdown and HTML Files Guidance Annotation

To ensure documentation quality and discoverability, include this annotation at the top of each Markdown or HTML file:

<!-- @guidance: This section should contain a general description and a section for references to child projects. -->

Use this annotation to remind contributors to provide meaningful overviews and maintain up-to-date references to related modules or subprojects.

Java and TypeScript Files Guidance Annotation

For Java and TypeScript source files, use the @guidance annotation within a multiline comment block (not in Javadoc or TSDoc comments).

Java package-level guidance (package-info.java):

package org.machanism.machai.maven;

/*
 * @guidance:
 *
 * 1. Document All Public and Protected Elements:
 *    - Ensure every public and protected class, interface, method, and field has a comprehensive Javadoc comment.
 *    - Include package-level Javadoc in a `package-info.java` file to describe the package’s purpose and usage.
 *
 * 2. Use Clear and Concise Descriptions:
 *    - Write meaningful summaries that explain the purpose, behavior, and usage of each element.
 *    - Avoid vague statements; be specific about functionality and intent.
 *
 * 3. Describe Parameters, Return Values, and Exceptions:
 *    - Use `@param` tags to document all method parameters.
 *    - Use `@return` tags to describe return values.
 *    - Use `@throws` or `@exception` tags to explain when exceptions are thrown.
 *
 * 4. Include Usage Examples Where Helpful:
 *    - Provide code snippets or examples in Javadoc comments for complex classes or methods.
 *
 * 5. Maintain Consistency and Formatting:
 *    - Follow a consistent style and structure for all Javadoc comments.
 *    - Use proper Markdown or HTML formatting for readability.
 *
 * 6. Update Javadoc with Code Changes:
 *    - Revise Javadoc comments whenever code is modified to ensure documentation remains accurate and up to date.
 *
 * 7. Leverage Javadoc Tools:
 *    - Use IDE features or static analysis tools to check for missing or incomplete Javadoc.
 *    - Generate and review Javadoc HTML output regularly to verify quality and completeness.
 *
 * 8. Note: `@guidance` is not a Javadoc tag. Do not use it within Javadoc comments.
 *
 * 9. Escape `<` and `>` as `&lt;` and `&gt;` in `<pre>` content for Javadoc.
 *
 * 10. Use the Java version specified in `pom.xml` for code generation.
 *
 * Apply these practices to all Java code within the package to ensure high-quality, maintainable, and user-friendly documentation.
 */

TypeScript example:

/*
 * @guidance:
 * - Document all exported classes, interfaces, functions, and constants using TSDoc.
 * - Provide clear descriptions, parameter details, and usage examples.
 * - Keep documentation up to date with code changes.
 * - Do not use `@guidance` within TSDoc comments.
 */

Python Guidance Annotation

For Python files, use a single-line comment at the top or relevant section:

# @guidance: Follow PEP 257 for docstrings. Document all public classes,
 methods, and functions. Keep comments up to date and clear.

Best Practices

  • Do not remove or delete any @guidance comments. These are essential for maintaining project standards and should remain intact during code updates and reviews.
  • Regularly review and update guidance annotations to reflect evolving best practices and project requirements.
  • Use automated tools where possible to check for compliance with guidance annotations:
https://www.free-Counters.org