Javadoc - Detailed Review
Coding Tools
Javadoc - Product Overview
Introduction to Javadoc
Javadoc is a versatile tool in the Java ecosystem that plays a crucial role in generating API documentation from comments embedded in Java source code.
Primary Function
The primary function of Javadoc is to parse Java source files and documentation comments, then generate a set of HTML pages that describe the API. This includes documentation for public and protected classes, interfaces, constructors, methods, and fields.
Target Audience
Javadoc is intended for a diverse audience, including Java developers, testers, and other stakeholders who need to understand the API and its usage. For developers, it provides detailed information about the code structure and functionality. For non-developers, such as testers or managers, it offers a clear and accessible way to comprehend the application without delving into the source code itself.
Key Features
Documentation Generation
Javadoc generates HTML-formatted API documentation from the comments in the source code. This documentation includes class hierarchies, method descriptions, and other relevant details.
Customizable Output
The tool allows for customization through the use of doclets. The standard doclet generates HTML output, but users can create or modify doclets to produce output in other formats such as XML, MIF, or RTF.
Search and Accessibility
Javadoc-generated documentation includes a search facility that enables users to find specific elements and key phrases within the API documentation. Additionally, the -linksource option allows users to link directly to the source code from the generated documentation, enhancing accessibility.
Module System Support
Javadoc supports documentation comments in module declarations, allowing for the generation of module-specific summary pages and configuration of the modules to be documented.
HTML and Markdown Support
Users can incorporate HTML and Markdown in their Javadoc comments to enhance the readability and structure of the generated documentation. This is particularly useful for audiences who prefer HTML documentation over in-code comments.
Error and Code Example Support
The tool includes features like DocLint for checking errors and improved support for code examples, making it easier to include and manage code snippets within the documentation.
By leveraging these features, Javadoc simplifies the process of creating and maintaining high-quality API documentation, making it an indispensable tool for Java developers and other stakeholders.
Javadoc - User Interface and Experience
User Interface and Experience of Javadoc
The user interface and experience of Javadoc, a tool for generating API documentation from Java source code, are centered around simplicity, clarity, and ease of use, particularly for developers.
Ease of Use
Javadoc is relatively straightforward to use, especially for those familiar with Java development. Here are some key aspects that contribute to its ease of use:
- Command-Line Interface: The `javadoc` command can be run from the command line, allowing developers to generate documentation by specifying the packages or source files they want to document. This process is simplified by options such as `-subpackages` and `-sourcepath` to handle package and directory specifications.
- IDE Integration: Most Integrated Development Environments (IDEs) like Eclipse, NetBeans, and IntelliJ IDEA have built-in support for generating Javadoc documentation, making it even easier for developers to create and manage their API documentation without leaving their development environment.
User Experience
The user experience with Javadoc is largely positive due to its automated and systematic approach to generating documentation:
- Automated Documentation: Javadoc automatically parses the Java source files and documentation comments to produce a well-structured HTML documentation set. This includes descriptions of classes, interfaces, constructors, methods, and fields, which helps in maintaining a consistent and comprehensive documentation.
- Standardized Comments: Javadoc comments follow a specific syntax (`/**` and `*/`) and use special tags (`@param`, `@return`, `@throws`, etc.) to provide semantic context. This standardization makes it easy for developers to write and read the documentation.
- Customization: Users can customize the output format using doclets, which allows for generating documentation in various formats such as HTML, XML, or RTF. This flexibility caters to different needs and preferences.
Engagement and Factual Accuracy
The engagement with Javadoc is enhanced by its ability to generate accurate and detailed documentation:
- Detailed Documentation: The tool ensures that the generated HTML documentation is accurate and reflects the actual implementation of the code. It includes features like documenting default constructors and loading all referenced classes to ensure completeness.
- Linking and Formatting: Javadoc allows the use of HTML tags within comments, enabling better formatting and linking between different parts of the documentation. This makes the generated documentation easy to navigate and understand.
Overall Experience
Overall, the user experience with Javadoc is positive due to its simplicity, automation, and customization options. It facilitates effective communication among team members, simplifies maintenance, and enhances the overall quality of the codebase by providing a clear and comprehensive documentation set. This makes Javadoc an indispensable tool in the Java development community.
Javadoc - Key Features and Functionality
The JavaDoc Tool
The JavaDoc tool, a key component of Java development, offers several significant features and functionalities that enhance the documentation and maintenance of Java code. Here are the main features and how they work:Generating HTML Output
JavaDoc generates HTML documentation from Java source files that contain documentation comments. This process involves running the `javadoc` tool with the standard doclet, which analyzes the source files and produces HTML pages that include class, method, and field descriptions.Documentation Comments
JavaDoc relies on special comments in the source code, denoted by `/** */`, to extract information and generate documentation. These comments can include tags such as `@author`, `@param`, `@return`, and `@throws` to provide detailed information about the code elements.Search Facility
The generated HTML documentation includes a search facility that allows users to search for elements and key phrases within the documentation. This search feature can redirect users to relevant pages based on their search queries.Module System Support
JavaDoc supports documentation comments in module declarations, which is particularly useful in Java 9 and later versions. It allows users to specify the set of modules to document and generates a summary page for the documented modules.Custom Doclets
JavaDoc is extensible through the use of custom doclets. A doclet is a program that analyzes the internal form of the source files and generates output files. Users can specify a different doclet to generate output other than the standard HTML, such as reports on misspelled words or grammatical errors.AI Integration
While the standard JavaDoc tool does not integrate AI directly, there are third-party plugins like the IntelliJ JavaDoc AI Plugin that leverage AI to generate JavaDoc comments. This plugin uses OpenAI’s GPT-3 API to provide intelligent and context-aware suggestions for documenting methods, classes, and interfaces. It automates the process of writing JavaDoc comments, making it more efficient and accurate.Benefits of AI-Powered JavaDoc Plugins
- Automatic Generation: These plugins simplify the process of writing JavaDoc comments by automatically generating them based on the code context.
- Context-Aware Suggestions: The AI-powered suggestions are more precise and meaningful because they analyze the surrounding code.
- Efficiency: This automation saves developers time and effort, allowing them to focus on other aspects of development.
- Consistency: AI-generated comments can help maintain a consistent documentation style across the project.
Conclusion
In summary, the JavaDoc tool is a powerful utility for generating and managing documentation in Java projects. While it does not inherently include AI, integrating AI through plugins can significantly enhance its functionality and efficiency. Javadoc - Performance and Accuracy
Performance Improvement
Incorporating Javadoc comments can significantly enhance the performance of automated test oracle generation (TOG). A study on the impact of Javadoc comments on TOG found that including these comments improves the accuracy of test oracles, often aligning closely with ground truth. This improvement is observed across various large language models (LLMs) and different prompt formats. Specifically, the study showed a 10-20% improvement in generating ground-truth test oracles when using Javadoc comments, even when compared to using the method under test (MUT) code alone.Valuable Components of Javadoc Comments
The components of Javadoc comments that are most valuable for TOG are the descriptions and the `@return` tags. These elements provide critical information about the functionality, parameters, return values, and exceptions, which are essential for accurate test oracle generation.Bug Detection
Javadoc comments also play a crucial role in detecting real-world bugs. When using Javadoc comments, the method developed in the study detected between 19% and 94% more real-world bugs in the Defects4J dataset compared to prior methods that used the MUT code. This indicates that Javadoc comments can be highly effective in bug detection even without access to the implementation code.AI-Generated Javadoc Comments
Tools like the IntelliJ JavaDoc AI Plugin utilize AI to generate Javadoc comments, which can also improve TOG performance. These generated comments, even when created by models like GPT-3.5, can enhance the accuracy of test oracles by about 10% compared to not using any Javadoc comments.Limitations
While Javadoc comments are highly beneficial, there are some limitations to consider:Quality Variability
The quality of developer-written Javadoc comments can vary significantly, which can affect their usefulness in TOG and bug detection.AI Model Dependency
AI-generated Javadoc comments rely on the capabilities and limitations of the underlying AI model, and their accuracy can be influenced by the model’s performance and the availability of the API.Code Snippet Inclusion
The process of including code snippets in Javadoc comments has historically been tedious, though improvements like the `@snippet` tag in Java 18 have simplified this process.Practical Usage
Tools such as the Javadoc tool and plugins like the IntelliJ JavaDoc AI Plugin facilitate the generation and use of Javadoc comments. The Javadoc tool can generate documentation even from incomplete or erroneous source code, which is useful for early-stage documentation. However, it does not perform thorough checks on the code, so additional tools like DocCheck may be necessary for more rigorous verification. In summary, Javadoc comments significantly enhance the performance and accuracy of automated testing and bug detection in software development, particularly when integrated with AI-driven tools. However, their effectiveness can be influenced by the quality of the comments and the capabilities of the AI models used. Javadoc - Pricing and Plans
The Pricing Structure and Plans for AI-Driven Javadoc Tools
The pricing structure and plans for AI-driven Javadoc tools, particularly those integrating with coding environments like IntelliJ or VS Code, are not directly tied to the traditional `javadoc` tool provided by Oracle. Instead, they often rely on external AI services and plugins. Here’s a breakdown of the relevant pricing and plans:
AI-Driven Javadoc Plugins
IntelliJ JavaDoc AI Plugin
- This plugin uses OpenAI’s GPT-3 API to generate JavaDoc comments.
- Pricing: The plugin itself is free, but it requires an API key from OpenAI, which involves a subscription. OpenAI’s API pricing varies based on usage, and there is no free tier for API access. You need to set up a subscription and obtain an API key to use the plugin.
AI Javadoc Writer
- This tool also leverages AI, specifically OpenAI’s GPT-4 architecture, to generate and regenerate Javadoc.
- Pricing: Similar to the IntelliJ plugin, this tool relies on OpenAI’s API, which means you need a subscription to use it. There is no free tier available for API access.
Key Features and Tiers
OpenAI API
- Pricing Tiers: OpenAI charges based on the number of API requests. There are no fixed tiers, but rather a pay-as-you-go model. The cost can vary depending on the specific model used (e.g., GPT-3, GPT-4) and the volume of requests.
- Features: Access to advanced natural language processing capabilities, context-aware suggestions, and the ability to generate high-quality JavaDoc comments.
Free Options
- There are no free options available for using these AI-driven Javadoc tools since they all require a subscription to OpenAI’s API. The free version of ChatGPT does not offer API access, resulting in errors like “429 Too Many Requests” if used without a subscription.
In summary, while the AI-driven Javadoc tools themselves may be free or open-source, their functionality relies on a subscription to OpenAI’s API, which incurs costs based on usage. There are no free tiers available for these services.
Javadoc - Integration and Compatibility
Integration with Other Tools
Javadoc, a tool for generating API documentation from Java source files, integrates seamlessly with various development tools and environments, enhancing the overall development experience.
IntelliJ IDEA
Javadoc is tightly integrated with IntelliJ IDEA, a popular integrated development environment (IDE). IntelliJ IDEA allows you to generate Javadoc references directly from the IDE, configure documentation paths, and view external Javadocs for any symbol or method signature right from the editor. You can add Javadoc comments using automatic completion, fix outdated comments, and render Javadocs in the editor for better readability.
Java Development Kit (JDK)
Javadoc is part of the JDK and works closely with other JDK tools. It reads Java source files and class files, generating HTML documentation that includes class hierarchies, use relationships, and user-supplied documentation comments. The tool can be customized using doclets, which are pluggable back ends that analyze the documentation comments and generate the desired output.
Custom Doclets and Tags
Javadoc supports the use of custom doclets and tags, allowing developers to extend its functionality. Custom tags can be recognized and included in the generated API reference by configuring the IDE settings or using command-line arguments. This flexibility makes Javadoc adaptable to various documentation needs.
Compatibility Across Platforms and Devices
Cross-Platform Compatibility
Javadoc is a Java-based tool, and as such, it is compatible with any platform that supports Java. This includes Windows, macOS, and Linux. The generated HTML documentation is also platform-independent, making it accessible from any device with a web browser.
Device Compatibility
Since Javadoc generates HTML output, the documentation can be viewed on any device with a web browser, including desktops, laptops, tablets, and smartphones. This ensures that developers and users can access the API documentation from a wide range of devices without any compatibility issues.
Additional Considerations
Locale and Encoding
Javadoc supports various locales and encodings, allowing developers to generate documentation in different languages and character sets. This is achieved through command-line arguments such as `-encoding`, `-docencoding`, and `-charset`, ensuring that the documentation is correctly displayed regardless of the locale or encoding used.
In summary, Javadoc integrates well with development tools like IntelliJ IDEA, is part of the JDK ecosystem, and offers cross-platform compatibility. Its ability to generate platform-independent HTML documentation makes it accessible across a wide range of devices, enhancing its utility in diverse development environments.
Javadoc - Customer Support and Resources
Documentation and Guides
The Javadoc tool comes with comprehensive documentation that includes detailed guides on how to write doc comments, use the tool, and customize the output. For authors writing API documentation, the “Documentation Comment Tag Specification for the Standard Doclet” is a valuable resource.
Command-Line Options and Customization
The Javadoc tool offers a range of command-line options that allow you to customize the content and format of the generated documentation. You can specify visibility levels (e.g., -public, -protected, -package, -private), include or exclude certain members, and link to external documentation using the -link option. Additionally, you can use custom tags and include additional resources like HTML or images in the generated Javadoc.
Integration with IDEs
Tools like IntelliJ IDEA provide integration with the Javadoc tool, making it easier to generate and manage documentation directly from the IDE. IntelliJ IDEA allows you to add Javadoc comments automatically, fix and update existing comments, render Javadocs in the editor, and generate a Javadoc reference for your project with various customization options.
Troubleshooting
For any issues that arise, the Javadoc documentation includes troubleshooting sections. For example, if you encounter errors like “Malformed locale name,” you can adjust the encoding and charset settings using options like -encoding, -docencoding, and -charset.
Additional Resources
- Custom Tags: You can use custom tags in your Javadoc comments and include them in your API reference guide by adding them as command-line arguments.
- Search and Summary Pages: The Standard Doclet generates output that enables users to search the documentation and provides summary pages for new API, deprecated API, and other useful information.
- Module System Support: The Javadoc tool supports documentation comments in module declarations, allowing for comprehensive documentation of modular projects.
Community and Support
While the provided resources do not explicitly mention a dedicated customer support service for Javadoc, the extensive documentation and community-driven resources (such as forums and Stack Overflow) often provide sufficient support for most users.
By leveraging these resources, you can effectively use the Javadoc tool to generate high-quality API documentation for your projects.
Javadoc - Pros and Cons
Advantages of Javadoc
Javadoc offers several significant advantages that make it a valuable tool in Java development:Consistency and Standardization
Javadoc provides a standard format for writing comments and documentation, ensuring consistency across the codebase. This standardization helps in maintaining a uniform style of documentation, making it easier for developers to follow and contribute to the project.Usability and Collaboration
Javadoc documentation is crucial for helping other developers understand and use the API more effectively. It facilitates better collaboration, especially when new team members or external developers need to get up to speed with the code. Well-documented code reduces the time spent deciphering what a piece of code is supposed to do, thereby increasing productivity.Maintenance and Updates
Javadoc makes code maintenance and updates easier. It provides a clear and structured format for documenting Java code, which helps in quickly identifying and updating the necessary parts of the codebase. This structured documentation also helps in ensuring that the code remains maintainable over time.Integration with IDEs
Javadoc can be integrated with Integrated Development Environments (IDEs) such as Eclipse and IntelliJ IDEA. This integration allows for real-time help and documentation, making it easier for developers to access and use the documentation directly within their development environment.Early Documentation
The Javadoc tool can generate documentation even from incomplete or erroneous source files, allowing developers to write documentation comments and generate API documentation early in the design phase, before the implementation is complete.Disadvantages of Javadoc
Despite its benefits, Javadoc also has some drawbacks:Poor Readability and Screen Space
Extensive use of Javadoc comments can make the source code less readable due to the limited screen space. This can lead to a cluttered view, making it harder for developers to get a clear overview of the code.Low Value Comments
Many Javadoc comments, especially those generated automatically, often provide little to no added value. They may explain the “what” but not the “why,” which is more important for understanding the developer’s intent. This can lead to a situation where comments are almost worthless.Maintenance of Comments
Comments can become outdated or incorrect over time, especially during enhancements, defects, or refactoring. If comments are not updated, they can be misleading, creating confusion between what the comment says and what the new implementation does.Slower Refactoring
Updating Javadoc comments is a manual process that can be time-consuming. This can slow down the refactoring process, as developers might avoid refactoring to avoid the additional task of updating the documentation.Overreliance on Text Descriptions
Pure text descriptions in Javadoc may not be as effective as other methods like using `assert` statements to check valid parameters. Automated checks can provide immediate feedback during development or testing, which can be more helpful than comments that might not be read. By weighing these advantages and disadvantages, developers can make informed decisions about when and how to use Javadoc effectively in their projects. Javadoc - Comparison with Competitors
Comparing IntelliJ JavaDoc AI Plugin with Other AI-Driven Tools
When comparing the IntelliJ JavaDoc AI Plugin with other AI-driven tools for generating and managing JavaDoc comments, several unique features and potential alternatives stand out.
IntelliJ JavaDoc AI Plugin
- This plugin utilizes OpenAI’s GPT-3 API to generate JavaDoc comments automatically, providing context-aware suggestions based on the code’s context.
- It simplifies the process of writing JavaDoc comments, allowing developers to focus on other aspects of their project.
- The plugin requires an API key from OpenAI, which may involve a subscription cost, but it ensures secure and managed access to the API.
- It integrates seamlessly with IntelliJ IDEA, enabling easy code navigation and review of generated JavaDoc comments.
AI Javadoc Writer (Using ChatGPT)
- This tool leverages ChatGPT based on OpenAI’s GPT-4 architecture to dynamically generate and regenerate up-to-date JavaDoc comments. It is proficient in understanding complex coding constructs and linguistic nuances, ensuring technically accurate and comprehensible documentation.
- Unlike the IntelliJ JavaDoc AI Plugin, this tool might not have a specific integration with an IDE but can be used through other interfaces like VS Code plugins.
GitHub Copilot
- While GitHub Copilot is not specifically focused on JavaDoc generation, it does offer automated code documentation generation as part of its broader set of features. It supports multiple programming languages, including Java, and integrates with popular IDEs like JetBrains.
- Copilot’s documentation generation is part of its overall code assistance capabilities, which include code autocompletion, test case generation, and code review suggestions.
- However, Copilot’s primary focus is on general coding tasks rather than specialized JavaDoc generation.
AskCodi
- AskCodi is another AI coding assistant that, while not specifically focused on JavaDoc generation, can help with code suggestions and improvements. It supports Java among other languages and integrates with IDEs like IntelliJ IDEA.
- AskCodi can analyze code and provide suggestions to improve it, but it does not have a dedicated feature for generating JavaDoc comments.
- It is more versatile in its capabilities, including answering coding-related queries and generating code in various languages.
Key Differences and Alternatives
- Specialization: The IntelliJ JavaDoc AI Plugin and the AI Javadoc Writer are more specialized in generating JavaDoc comments, making them ideal for developers who need high-quality, context-aware documentation.
- Integration: The IntelliJ JavaDoc AI Plugin has a direct integration with IntelliJ IDEA, which can be a significant advantage for developers already using this IDE. GitHub Copilot and AskCodi offer broader integration with multiple IDEs but lack the specialized focus on JavaDoc.
- Cost: Both the IntelliJ JavaDoc AI Plugin and the AI Javadoc Writer require access to OpenAI APIs, which may involve subscription costs. GitHub Copilot and AskCodi also offer paid plans for advanced features, but they have free versions available as well.
- Versatility: GitHub Copilot and AskCodi are more versatile tools that can assist with a wide range of coding tasks beyond just JavaDoc generation.
In summary, if your primary need is automated, high-quality JavaDoc generation with context-aware suggestions, the IntelliJ JavaDoc AI Plugin or the AI Javadoc Writer might be the best choice. However, if you are looking for a more comprehensive coding assistant that can help with various aspects of development, GitHub Copilot or AskCodi could be more suitable alternatives.
Javadoc - Frequently Asked Questions
Frequently Asked Questions about Javadoc
1. What is Javadoc and what is it used for?
Javadoc is a tool provided by Oracle that generates API documentation in HTML format from doc comments in Java source code. It helps developers create and maintain clear, readable documentation for their Java programs, making it easier for others to use and understand the code.2. How do you write doc comments for Javadoc?
To write doc comments for Javadoc, you start with the `/**` delimiter and end with the `*/` delimiter. The first line should be a short summary of the method or class, and subsequent lines can include detailed descriptions. You can use various tags such as `@param`, `@return`, and `@throws` to document parameters, return values, and exceptions. It is also important to keep each line to 80 characters or less to avoid wrapping.3. What types of source files can Javadoc process?
Javadoc can generate output from several types of source files, including Java class files (.java), package comment files, overview comment files, and miscellaneous unprocessed files like images, sample source code, and HTML files.4. What are the common Javadoc tags and their uses?
Common Javadoc tags include `@param` to describe method parameters, `@return` to describe the return value of a method, `@throws` to document exceptions thrown by a method, `@see` to reference other classes or methods, and `@link` to create hyperlinks to other documentation. These tags help in organizing and making the documentation more informative.5. How do you generate Javadoc documentation?
To generate Javadoc documentation, you use the Javadoc tool, which is part of the Java Development Kit (JDK). You can run the tool from the command line, specifying the source files and any additional options as needed. For example, `javadoc -d doc package1 package2` will generate documentation for the specified packages and save it in the `doc` directory.6. What is the purpose of the `@author` tag in Javadoc?
The `@author` tag is used to specify the author of a class or method. This information is included in the generated HTML documentation, providing credit to the person who wrote the code and helping in tracking the origin of different parts of the program.7. How do you include images and other files in Javadoc documentation?
You can include images and other files in Javadoc documentation by referencing them within your doc comments. For example, you can use the `@image` tag or simply include the image file path in your comment. These files are then included in the generated HTML documentation.8. Can Javadoc handle multiple paragraphs and formatting?
Yes, Javadoc can handle multiple paragraphs and basic formatting. You can separate paragraphs using the `` tag, and you can use HTML tags within your doc comments to apply formatting such as bold, italic, and lists.
9. What are the benefits of using Javadoc for documentation?
Using Javadoc for documentation provides several benefits, including standardized and consistent documentation, ease of maintenance, and automatic generation of HTML documentation. This makes it easier for developers to understand and use the code, and it also helps in maintaining code quality and readability.10. Are there any specific conventions or best practices for writing Javadoc comments?
Yes, there are specific conventions and best practices for writing Javadoc comments. For example, the first sentence should be a short summary, and subsequent lines should provide detailed descriptions. It is also recommended to keep lines short (80 characters or less) and to use blank lines to separate the description from the list of tags. Following these conventions ensures that the generated documentation is clear and readable. Javadoc - Conclusion and Recommendation
Final Assessment of Javadoc
Javadoc is a versatile and essential tool in the Java Development Kit (JDK) that generates API documentation in HTML format from Java source code. Here’s a comprehensive overview of its benefits, who would benefit most from using it, and an overall recommendation.Benefits of Javadoc
- Improved Code Quality: Well-documented code is easier to maintain and less prone to errors. Javadoc ensures that your code is consistently documented, making it more readable and maintainable.
- Enhanced Collaboration: New team members or external developers can quickly understand the codebase with well-documented APIs. This facilitates better collaboration and reduces the time spent onboarding new team members.
- Increased Productivity: Developers spend less time deciphering what a piece of code is supposed to do when it is well-documented. This leads to increased productivity and faster development cycles.
- Standardization: Javadoc provides a standard format for writing comments and documentation, ensuring consistency across the codebase.
- Integration with Tools: Javadoc integrates smoothly with Integrated Development Environments (IDEs) like Eclipse and IntelliJ IDEA, and build tools like Maven and Gradle. This allows for real-time help and documentation, making the development process more efficient.
Who Would Benefit Most
- Java Developers: Any developer working with Java can significantly benefit from using Javadoc. It helps in documenting code in a standardized format that other developers can easily understand.
- Large Project Teams: In larger projects, maintaining consistent and up-to-date documentation is crucial. Javadoc is particularly useful here as it ensures that the documentation evolves with the code and is always accessible.
- Non-Developers: Test personnel, managers, and other stakeholders who need to understand the application without delving into the source code can benefit from the HTML documentation generated by Javadoc.
Best Practices and Recommendations
- Audience-Centric Documentation: Consider who will be using your Javadoc when deciding what to document. This ensures that the documentation is relevant and useful to the intended audience.
- Concise and Useful Comments: The first sentence of the Javadoc comment is especially vital as it appears in summary information. Keep it concise and useful.
- Use of HTML: Use HTML carefully in Javadoc comments, depending on whether the audience prefers HTML documentation or in-code comments.
- Integration with Development Workflow: Use Javadoc in conjunction with IDEs and build tools to automate the documentation process and ensure it is always up-to-date.