Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update javadoc for Context.register #3

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update javadoc for Context.register #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions src/main/java/org/crac/Context.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,12 @@ public abstract void beforeCheckpoint(Context<? extends Resource> context)
public abstract void afterRestore(Context<? extends Resource> context)
throws RestoreException;

/**
* Registers a {@code Resource} with this {@code Context}.
/**
* Registers a {@code Resource} with this {@code Context}
*
* <p> Context maintains a weak reference to registered Resource, thus client code must maintain a strong reference
* to the Resource to guarantee `beforeCheckpoint` and `afterRestore` methods execution.
Comment on lines +52 to +53
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First of all, thank you for the PR!

Regarding the change, should it really be in the description of the abstract register method? For example, there can be an another Context implementaion that in contrast maintains strong links (A {@code Context} implementor is encouraged to respect properties of the global {@code Context}, but that is not mandatory). But I support any improvements for clarity. Does it make sense to make a reference for the global context properties (https://github.com/CRaC/org.crac/blob/master/src/main/java/org/crac/package-info.java#L68)(https://javadoc.io/doc/io.github.crac/org-crac/latest/index.html, Global Context Properties)) somehow?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi Anton, I think you are right, documenting implementation details for an abstract method could look confusing. Let me think what would be the best avenue for this and I will get back to you. Thanks for your feedback 👍

* Otherwise, depending on garbage collector cycles, they may or may not be executed.
*
* @param resource {@code Resource} to be registered.
* @throws NullPointerException if {@code resource} is {@code null}
Expand Down