Skip to content

AI Ghostwriter

AI Ghostwriter is an intelligent documentation and code guidance engine designed to automate, standardize, and enhance project documentation and code annotation across multi-module Java projects. By leveraging AI-driven best practices, it ensures consistency, clarity, and maintainability throughout your codebase and documentation assets.

Project Layers

AI Ghostwriter operates across multiple layers of your project, including:

  • Root and Module Folders: Enforces the presence and correctness of essential files such as LICENSE.txt, README.md, and @guidance.txt.
  • Documentation Files: Provides guidance annotations for Markdown and HTML files to ensure comprehensive project and module descriptions.
  • Source Code Files: Embeds best practice guidance for Java, TypeScript, and Python files, promoting high-quality code documentation and maintainability.

Guidance Annotations

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

Folder Level Guidance

File name: @guidance.txt

This file should be placed in the root directory of your project and may be included in submodules as needed. It provides 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 the following 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. This is not a Javadoc or TypeScriptdoc tag and should not be placed within documentation comments.

Example for 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.
 */

Example for TypeScript:

/*
 * @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 of the file:

# @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