From 125698c6056dfd86d95d93b62aca98d128ec135e Mon Sep 17 00:00:00 2001
From: Steven Hartland <stevenmhartland@gmail.com>
Date: Fri, 9 Aug 2024 11:32:15 +0100
Subject: [PATCH] docs: improve docs for container methods (#2713)

Improve the documentation for container Terminate and IsRunning methods.
---
 container.go |  7 +++++--
 docker.go    | 13 +++++++++----
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/container.go b/container.go
index b772ba948f..6f17a7e3ff 100644
--- a/container.go
+++ b/container.go
@@ -43,10 +43,13 @@ type Container interface {
 	MappedPort(context.Context, nat.Port) (nat.Port, error)         // get externally mapped port for a container port
 	Ports(context.Context) (nat.PortMap, error)                     // Deprecated: Use c.Inspect(ctx).NetworkSettings.Ports instead
 	SessionID() string                                              // get session id
-	IsRunning() bool
+	IsRunning() bool                                                // IsRunning returns true if the container is running, false otherwise.
 	Start(context.Context) error                                    // start the container
 	Stop(context.Context, *time.Duration) error                     // stop the container
-	Terminate(context.Context) error                                // terminate the container
+
+	// Terminate stops and removes the container and its image if it was built and not flagged as kept.
+	Terminate(ctx context.Context) error
+
 	Logs(context.Context) (io.ReadCloser, error)                    // Get logs of the container
 	FollowOutput(LogConsumer)                                       // Deprecated: it will be removed in the next major release
 	StartLogProducer(context.Context, ...LogProductionOption) error // Deprecated: Use the ContainerRequest instead
diff --git a/docker.go b/docker.go
index bc99cbc2dd..f6308f1d33 100644
--- a/docker.go
+++ b/docker.go
@@ -244,15 +244,20 @@ func (c *DockerContainer) Start(ctx context.Context) error {
 	return nil
 }
 
-// Stop will stop an already started container
+// Stop stops the container.
 //
-// In case the container fails to stop
-// gracefully within a time frame specified by the timeout argument,
-// it is forcefully terminated (killed).
+// In case the container fails to stop gracefully within a time frame specified
+// by the timeout argument, it is forcefully terminated (killed).
 //
 // If the timeout is nil, the container's StopTimeout value is used, if set,
 // otherwise the engine default. A negative timeout value can be specified,
 // meaning no timeout, i.e. no forceful termination is performed.
+//
+// All hooks are called in the following order:
+//   - [ContainerLifecycleHooks.PreStops]
+//   - [ContainerLifecycleHooks.PostStops]
+//
+// If the container is already stopped, the method is a no-op.
 func (c *DockerContainer) Stop(ctx context.Context, timeout *time.Duration) error {
 	err := c.stoppingHook(ctx)
 	if err != nil {