update doc and normalize API

browser.go

@@ -123,7 +123,8 @@ func (b *Browser) DefaultViewport(viewport *proto.EmulationSetDeviceMetricsOverr
 	return b
 }
 
-// Connect doc is similar to the method MustConnect
+// Connect to the browser and start to control it.
+// If fails to connect, try to launch a local browser, if local browser not found try to download one.
 func (b *Browser) Connect() error {
 	if b.client == nil {
 		u := defaults.URL
@@ -154,13 +155,12 @@ func (b *Browser) Connect() error {
 	return b.setHeadless()
 }
 
-// Close doc is similar to the method MustClose
+// Close the browser
 func (b *Browser) Close() error {
 	return proto.BrowserClose{}.Call(b)
 }
 
-// Page doc is similar to the method MustPage
-// If url is empty, the default target will be "about:blank".
+// Page creates a new browser tab. If url is empty, the default target will be "about:blank".
 func (b *Browser) Page(url string) (p *Page, err error) {
 	target, err := proto.TargetCreateTarget{
 		URL:              "about:blank",
@@ -184,7 +184,7 @@ func (b *Browser) Page(url string) (p *Page, err error) {
 	return
 }
 
-// Pages doc is similar to the method MustPages
+// Pages retrieves all visible pages
 func (b *Browser) Pages() (Pages, error) {
 	list, err := proto.TargetGetTargets{}.Call(b)
 	if err != nil {

element.go

@@ -27,7 +27,7 @@ type Element struct {
 	ObjectID proto.RuntimeRemoteObjectID
 }
 
-// Focus doc is similar to the method MustFocus
+// Focus sets focus on the specified element
 func (el *Element) Focus() error {
 	err := el.ScrollIntoView()
 	if err != nil {
@@ -38,7 +38,8 @@ func (el *Element) Focus() error {
 	return err
 }
 
-// ScrollIntoView doc is similar to the method MustScrollIntoViewIfNeeded
+// ScrollIntoView scrolls the current element into the visible area of the browser
+// window if it's not already within the visible area.
 func (el *Element) ScrollIntoView() error {
 	defer el.tryTraceInput("scroll into view")()
 	el.page.browser.trySlowmotion()
@@ -171,7 +172,7 @@ func (el *Element) Box() (*proto.DOMRect, error) {
 	return res.Model.Rect(), nil
 }
 
-// Press doc is similar to the method MustPress
+// Press a key
 func (el *Element) Press(key rune) error {
 	err := el.WaitVisible()
 	if err != nil {
@@ -188,7 +189,7 @@ func (el *Element) Press(key rune) error {
 	return el.page.Keyboard.Press(key)
 }
 
-// SelectText doc is similar to the method MustSelectText
+// SelectText selects the text that matches the regular expression
 func (el *Element) SelectText(regex string) error {
 	err := el.Focus()
 	if err != nil {
@@ -202,7 +203,7 @@ func (el *Element) SelectText(regex string) error {
 	return err
 }
 
-// SelectAllText doc is similar to the method MustSelectAllText
+// SelectAllText selects all text
 func (el *Element) SelectAllText() error {
 	err := el.Focus()
 	if err != nil {
@@ -216,7 +217,8 @@ func (el *Element) SelectAllText() error {
 	return err
 }
 
-// Input doc is similar to the method MustInput
+// Input focus the element and input text to it.
+// To empty the input you can use something like el.SelectAllText().MustInput("")
 func (el *Element) Input(text string) error {
 	err := el.WaitVisible()
 	if err != nil {
@@ -245,7 +247,7 @@ func (el *Element) Blur() error {
 	return err
 }
 
-// Select doc is similar to the method MustSelect
+// Select the children option elements that match the selectors, the selector can be text content or css selector
 func (el *Element) Select(selectors []string) error {
 	err := el.WaitVisible()
 	if err != nil {
@@ -292,7 +294,7 @@ func (el *Element) Property(name string) (proto.JSON, error) {
 	return prop.Value, nil
 }
 
-// SetFiles doc is similar to the method MustSetFiles
+// SetFiles of the current file input element
 func (el *Element) SetFiles(paths []string) error {
 	absPaths := []string{}
 	for _, p := range paths {
@@ -312,8 +314,7 @@ func (el *Element) SetFiles(paths []string) error {
 	return err
 }
 
-// Describe doc is similar to the method MustDescribe
-// please see https://chromedevtools.github.io/devtools-protocol/tot/DOM/#method-describeNode
+// Describe the current element
 func (el *Element) Describe(depth int, pierce bool) (*proto.DOMNode, error) {
 	val, err := proto.DOMDescribeNode{ObjectID: el.ObjectID, Depth: int64(depth), Pierce: pierce}.Call(el)
 	if err != nil {
@@ -374,7 +375,7 @@ func (el *Element) ContainsElement(target *Element) (bool, error) {
 	return res.Value.Bool(), nil
 }
 
-// Text doc is similar to the method MustText
+// Text that the element displays
 func (el *Element) Text() (string, error) {
 	str, err := el.EvalWithOptions(jsHelper(js.Text, nil))
 	if err != nil {
@@ -383,7 +384,7 @@ func (el *Element) Text() (string, error) {
 	return str.Value.String(), nil
 }
 
-// HTML doc is similar to the method MustHTML
+// HTML of the element
 func (el *Element) HTML() (string, error) {
 	str, err := el.Eval(`this.outerHTML`)
 	if err != nil {
@@ -392,7 +393,7 @@ func (el *Element) HTML() (string, error) {
 	return str.Value.String(), nil
 }
 
-// Visible doc is similar to the method MustVisible
+// Visible returns true if the element is visible on the page
 func (el *Element) Visible() (bool, error) {
 	res, err := el.EvalWithOptions(jsHelper(js.Visible, nil))
 	if err != nil {
@@ -401,7 +402,7 @@ func (el *Element) Visible() (bool, error) {
 	return res.Value.Bool(), nil
 }
 
-// WaitLoad for element like <img />
+// WaitLoad for element like <img>
 func (el *Element) WaitLoad() error {
 	_, err := el.EvalWithOptions(jsHelper(js.WaitLoad, nil))
 	return err
@@ -441,7 +442,7 @@ func (el *Element) WaitStable(interval time.Duration) error {
 	return nil
 }
 
-// Wait doc is similar to the method MustWait
+// Wait until the js returns true
 func (el *Element) Wait(js string, params ...interface{}) error {
 	return utils.Retry(el.ctx, el.sleeper(), func() (bool, error) {
 		res, err := el.Eval(js, params...)
@@ -457,13 +458,13 @@ func (el *Element) Wait(js string, params ...interface{}) error {
 	})
 }
 
-// WaitVisible doc is similar to the method MustWaitVisible
+// WaitVisible until the element is visible
 func (el *Element) WaitVisible() error {
 	opts := jsHelper(js.Visible, nil)
 	return el.Wait(opts.JS, opts.JSArgs...)
 }
 
-// WaitInvisible doc is similar to the method MustWaitInvisible
+// WaitInvisible until the element invisible
 func (el *Element) WaitInvisible() error {
 	opts := jsHelper(js.Invisible, nil)
 	return el.Wait(opts.JS, opts.JSArgs...)
@@ -483,7 +484,7 @@ func (el *Element) CanvasToImage(format string, quality float64) ([]byte, error)
 	return bin, nil
 }
 
-// Resource doc is similar to the method MustResource
+// Resource returns the "src" content of current element. Such as the jpg of <img src="a.jpg">
 func (el *Element) Resource() ([]byte, error) {
 	src, err := el.EvalWithOptions(jsHelper(js.Resource, nil))
 	if err != nil {
@@ -542,7 +543,7 @@ func (el *Element) Screenshot(format proto.PageCaptureScreenshotFormat, quality
 	return el.page.Root().Screenshot(false, opts)
 }
 
-// Release doc is similar to the method MustRelease
+// Release the remote object reference
 func (el *Element) Release() error {
 	return el.page.Context(el.ctx).Release(el.ObjectID)
 }
@@ -552,12 +553,12 @@ func (el *Element) CallContext() (context.Context, proto.Client, string) {
 	return el.ctx, el.page.browser, string(el.page.SessionID)
 }
 
-// Eval doc is similar to the method MustEval
+// Eval js on the page. For more info check the Element.EvalWithOptions
 func (el *Element) Eval(js string, params ...interface{}) (*proto.RuntimeRemoteObject, error) {
 	return el.EvalWithOptions(NewEvalOptions(js, params))
 }
 
-// EvalWithOptions of Eval
+// EvalWithOptions is just a shortcut of Page.EvalWithOptions with ThisID set to current element.
 func (el *Element) EvalWithOptions(opts *EvalOptions) (*proto.RuntimeRemoteObject, error) {
 	return el.page.Context(el.ctx).EvalWithOptions(opts.This(el.ObjectID))
 }

examples_test.go

@@ -42,10 +42,10 @@ func Example() {
 	// Eval js on the page
 	page.MustEval(`console.log("hello world")`)
 
-	// Pass parameters as json objects to the js function. This one will return 3
+	// Pass parameters as json objects to the js function. This MustEval will result 3
 	fmt.Println("1 + 2 =", page.MustEval(`(a, b) => a + b`, 1, 2).Int())
 
-	// When eval on an element, you can use "this" to access the DOM element.
+	// When eval on an element, "this" in the js is the current DOM element.
 	fmt.Println(page.MustElement("title").MustEval(`this.innerText`).String())
 
 	// Output:
@@ -475,6 +475,24 @@ func Example_hijack_requests() {
 	// Output: done
 }
 
+// Shows how to share a remote object reference between two Eval
+func Example_reuse_remote_object() {
+	page := rod.New().MustConnect().MustPage("")
+
+	fn, _ := page.EvalWithOptions(&rod.EvalOptions{JS: `Math.random`})
+
+	res, _ := page.EvalWithOptions(&rod.EvalOptions{
+		ByValue: true,
+		JSArgs: rod.JSArgs{
+			fn.ObjectID, // use remote function as the js argument x
+		},
+		JS: `x => x()`,
+	})
+
+	// print a random number
+	fmt.Println(res.Value.Num)
+}
+
 // Shows how to update the state of the current page.
 // In this example we enable the network domain.
 func Example_states() {

input.go

@@ -25,7 +25,7 @@ func (k *Keyboard) getModifiers() int64 {
 	return k.modifiers
 }
 
-// Down doc is similar to the method MustDown
+// Down holds the key down
 func (k *Keyboard) Down(key rune) error {
 	k.Lock()
 	defer k.Unlock()
@@ -40,7 +40,7 @@ func (k *Keyboard) Down(key rune) error {
 	return nil
 }
 
-// Up doc is similar to the method MustUp
+// Up releases the key
 func (k *Keyboard) Up(key rune) error {
 	k.Lock()
 	defer k.Unlock()
@@ -55,7 +55,7 @@ func (k *Keyboard) Up(key rune) error {
 	return nil
 }
 
-// Press doc is similar to the method MustPress
+// Press a key. It's a combination of Keyboard.Down and Keyboard.Up
 func (k *Keyboard) Press(key rune) error {
 	k.Lock()
 	defer k.Unlock()
@@ -79,7 +79,7 @@ func (k *Keyboard) Press(key rune) error {
 	return nil
 }
 
-// InsertText doc is similar to the method MustInsertText
+// InsertText is like pasting text into the page
 func (k *Keyboard) InsertText(text string) error {
 	k.Lock()
 	defer k.Unlock()
@@ -193,7 +193,7 @@ func (m *Mouse) Scroll(offsetX, offsetY float64, steps int) error {
 	return nil
 }
 
-// Down doc is similar to the method MustDown
+// Down holds the button down
 func (m *Mouse) Down(button proto.InputMouseButton, clicks int64) error {
 	m.Lock()
 	defer m.Unlock()
@@ -218,7 +218,7 @@ func (m *Mouse) Down(button proto.InputMouseButton, clicks int64) error {
 	return nil
 }
 
-// Up doc is similar to the method MustUp
+// Up releases the button
 func (m *Mouse) Up(button proto.InputMouseButton, clicks int64) error {
 	m.Lock()
 	defer m.Unlock()
@@ -248,7 +248,7 @@ func (m *Mouse) Up(button proto.InputMouseButton, clicks int64) error {
 	return nil
 }
 
-// Click doc is similar to the method MustClick
+// Click the button. It's the combination of Mouse.Down and Mouse.Up
 func (m *Mouse) Click(button proto.InputMouseButton) error {
 	if m.page.browser.trace {
 		defer m.page.Overlay(0, 0, 200, 0, "click "+string(button))()

lib/cdp/client.go

@@ -138,7 +138,7 @@ func (cdp *Client) Connect(ctx context.Context) error {
 	return nil
 }
 
-// MustConnect to browser
+// MustConnect is similar to Connect
 func (cdp *Client) MustConnect(ctx context.Context) *Client {
 	utils.E(cdp.Connect(ctx))
 	return cdp

lib/examples/compare-chromedp/emulate/main.go

@@ -20,7 +20,7 @@ func main() {
 	// reset
 	page.MustEmulate(devices.Clear)
 
-	page.MustViewport(1920, 2000, 1, false)
+	page.MustSetViewport(1920, 2000, 1, false)
 	page.MustNavigate("https://www.whatsmyua.info/?a")
 	page.MustScreenshot("screenshot2.png")
 }

lib/launcher/launcher.go

@@ -277,16 +277,16 @@ func (l *Launcher) Logger(w io.Writer) *Launcher {
 	return l
 }
 
-// MustLaunch a standalone temp browser instance and returns the debug url.
-// bin and profileDir are optional, set them to empty to use the default values.
-// If you want to reuse sessions, such as cookies, set the userDataDir to the same location.
+// MustLaunch is similar to Launch
 func (l *Launcher) MustLaunch() string {
 	u, err := l.Launch()
 	utils.E(err)
 	return u
 }
 
-// Launch doc is similar to the method MustLaunch
+// Launch a standalone temp browser instance and returns the debug url.
+// bin and profileDir are optional, set them to empty to use the default values.
+// If you want to reuse sessions, such as cookies, set the userDataDir to the same location.
 func (l *Launcher) Launch() (string, error) {
 	defer l.ctxCancel()