Documenting Objects and Modules

Oct 13, 2025 by pinkandtrash.com 95 views

Introduction

The MontePy API has become congested and difficult to work with, making it challenging for users to navigate and understand the package's structure. To address this issue, we propose a series of refactorings to improve the package hierarchy, documentation, and organization. Our goal is to create a more intuitive and user-friendly API that meets the needs of developers and users alike.

Documenting Objects and Modules

One of the primary concerns with the current package hierarchy is the lack of documentation. To address this, we suggest documenting objects more so than modules. This approach will provide a clearer understanding of the package's functionality and make it easier for users to find the information they need.

Documenting by Import Rather than File Hierarchy

Another issue with the current package hierarchy is that it is organized by file hierarchy rather than import. This can lead to confusion and make it difficult for users to find the information they need. To resolve this, we propose documenting the package by import rather than file hierarchy. This will provide a more logical and intuitive structure for users to navigate.

Moving Private Functions and Classes

To further simplify the package hierarchy, we suggest moving a lot of private functions and classes to a _private module. This will help to declutter the main package and make it easier for users to understand the public API.

Moving `montepy.input_parser` to `montepy._input_parser`

One of the first steps in this process is to move the montepy.input_parser module to montepy._input_parser. This will help to declutter the main package and make it easier for users to understand the public API.

# Before
import montepy.input_parser

# After
import montepy._input_parser

Creating a `_abc` or `abc` Module for Abstract Classes

Another step in this process is to create a _abc or abc module for abstract classes. This will help to organize abstract classes in a separate module and make it easier for users to find the information they need.

# Before
from montepy import AbstractClass

# After
from montepy._abc import AbstractClass

Making @tjlaboss Happy

Finally, we propose making @tjlaboss happy by implementing the suggested refactorings. This will help to ensure that the package hierarchy is simplified and easier to work with.

Benefits of the Refactorings

The proposed refactorings will provide several benefits, including:

Improved documentation: By documenting objects more so than modules, users will have a clearer understanding of the package's functionality.
Simplified package hierarchy: By moving private functions and classes to a _private module, the main package will be decluttered and easier to understand.
Easier navigation: By documenting the package by import rather than file hierarchy, users will find it easier to navigate the package and find the information they need.
Increased user satisfaction: By making the package hierarchy simpler and easier to work with, users will be more satisfied with the package and more likely to use it.

Conclusion

In conclusion, the proposed refactorings will help to simplify the MontePy API and make it easier to work with. By documenting objects more so than modules, moving private functions and classes to a _private module, and documenting the package by import rather than file hierarchy, we can create a more intuitive and user-friendly API that meets the needs of developers and users alike.

Future Work

Future work will focus on implementing the proposed refactorings and ensuring that the package hierarchy is simplified and easier to work with. We will also continue to monitor user feedback and make adjustments as needed to ensure that the package meets the needs of its users.

Commit Messages

To track the progress of the refactorings, we will use the following commit messages:

refactor: move input_parser to _input_parser
refactor: create _abc module for abstract classes
refactor: document package by import rather than file hierarchy
refactor: simplify package hierarchy by moving private functions and classes to _private module

API Documentation

To provide a clear understanding of the package's functionality, we will update the API documentation to reflect the changes made during the refactorings. This will include updating the documentation for each module and function to reflect the changes made.

Testing

To ensure that the refactorings do not introduce any bugs, we will update the testing framework to reflect the changes made during the refactorings. This will include updating the test cases for each module and function to reflect the changes made.

Deployment

Once the refactorings are complete, we will deploy the updated package to ensure that it is available to users. We will also provide documentation on how to update to the new version of the package.

Conclusion

Introduction

In our previous article, we discussed the proposed refactorings to simplify the MontePy API and make it easier to work with. In this article, we will answer some of the frequently asked questions (FAQs) about the refactorings.

Q: Why do we need to refactor the package hierarchy?

A: The current package hierarchy is congested and difficult to work with, making it challenging for users to navigate and understand the package's structure. By refactoring the package hierarchy, we can create a more intuitive and user-friendly API that meets the needs of developers and users alike.

Q: What are the benefits of documenting objects more so than modules?

A: By documenting objects more so than modules, users will have a clearer understanding of the package's functionality. This will make it easier for users to find the information they need and reduce the time spent searching for documentation.

Q: Why do we need to move private functions and classes to a `_private` module?

A: By moving private functions and classes to a _private module, we can declutter the main package and make it easier for users to understand the public API. This will also help to reduce the complexity of the package and make it easier to maintain.

Q: How will the refactorings affect the package's performance?

A: The refactorings will not affect the package's performance. The changes made will be purely organizational and will not impact the package's functionality or performance.

Q: Will the refactorings break any existing code?

A: The refactorings will not break any existing code. We will ensure that all existing code continues to work as expected after the refactorings are complete.

Q: How will the refactorings be tested?

A: We will update the testing framework to reflect the changes made during the refactorings. This will include updating the test cases for each module and function to reflect the changes made.

Q: When will the refactorings be deployed?

A: The refactorings will be deployed once they are complete. We will provide documentation on how to update to the new version of the package.

Q: Who will be responsible for maintaining the package after the refactorings?

A: The package will continue to be maintained by the same team that maintains it currently. We will ensure that the package remains up-to-date and continues to meet the needs of its users.

Q: How can users provide feedback on the refactorings?

A: Users can provide feedback on the refactorings by submitting issues or pull requests on the package's GitHub repository. We will also provide a contact email address for users to reach out to us with any questions or concerns.

Q: What is the timeline for the refactorings?

A: The timeline for the refactorings is as follows:

Week 1-2: Refactor the package hierarchy to document objects more so than modules.
Week 3-4: Move private functions and classes to a _private module.
Week 5-6: Document the package by import rather than file hierarchy.
Week 7-8: Test and deploy the refactorings.