help files for s3 methods

[till-tietz]

not sure if this will do the trick but here is a stackoverflow issue about this

https://stackoverflow.com/questions/7198758/roxygen2-how-to-properly-document-s3-methods

[gerasy1987]

Seems that despite the fact that S3 methods are not exported in package, you can still access the help files for them using ?plot.causal_model or ?print.causal_model (the latter works on master branch since I documented that method). So all we need is to write a proper roxygen2 skeleton for plot.causal_model.

@till-tietz @macartan I see that plot_dag() has a help file now but it is not intended to be used by users. Do we need to keep plot_dag() at all or could it be worth it to superseed this function by plot.causal_model() and then document the plot method? Right now it does not make sense since plot method is just a wrapper for plot_dag().

[macartan]

Yes that’s the issue with the help for plot_dag. It’s always been documented but not exported I often do ?CausalQueries:::plot_dag to see options, but how will anyone else know to do that ?plot.causal_model Is good for people who understand methods but if it’s not listed as a function it’s still hard to find I wonder if we should just export plot_dag so that people can see it and the help. We could rename it to plot_model to be consistent with other functions and then plot() is just a handy way to call plot_model ?

…

On Thu 14. Mar 2024 at 19:37, Georgiy (Gosha) Syunyaev < ***@***.***> wrote: Seems that despite the fact that S3 methods are not exported in package, you can still access the help files for them using ?plot.causal_model or ?print.causal_model (the latter works on master branch since I documented that method). So all we need is to write a proper roxygen2 skeleton for plot.causal_model. @till-tietz <https://github.com/till-tietz> @macartan <https://github.com/macartan> I see that plot_dag() has a help file now but it is not intended to be used by users. Do we need to keep plot_dag() at all or could it be worth it to move all of that to plot.causal_model() and then write a proper skeleton there? — Reply to this email directly, view it on GitHub <#323 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADBE57P2UWJGECGX6HOAGYLYYH4AXAVCNFSM6AAAAABEWL5LFCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOJYGI4TCMJZGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[gerasy1987]

@macartan this could be a solution, yes. I'm pretty sure we can add a see also section to the help file and reference the plot method.

[macartan]

Great

…

On Thu 14. Mar 2024 at 20:44, Georgiy (Gosha) Syunyaev < ***@***.***> wrote: @macartan <https://github.com/macartan> this could be a solution, yes. I'm pretty sure we can add a see also section to the help file and reference the plot method. — Reply to this email directly, view it on GitHub <#323 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADBE57OFV73QX4TJBWWDFKTYYID3DAVCNFSM6AAAAABEWL5LFCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSOJYGQ2TGNJQGY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[gerasy1987]

There is a way to force print help information for methods inside help file of "parent" function: we just need to us @rdname [FUNCTION_NAME], e.g.

@rdname summary.causal_model

This makes me think whether we want to have a special help page for causal_model-class where we can print all corresponding S3 methods. I tried to look for it, and it is not very straightforward for S3 as opposed to S4, but could be possible.

[till-tietz]

@gerasy1987 I think your proposal above would be fantastic!!! Let's see if we can figure it out

[gerasy1987]

I already implemented the brute force approach with @rdname for print and summary methods for causal_model class objects produced by update_model(). Now the issue here is that those print and summary methods also apply to make_model() function, but there is no easy way to include those methods in two help files ( see here )

Given that S3Class does not really support standalone help pages, maybe the way to go is to list all relevant S3 Methods (including plot) in the most base function that produces the causal_model class, i.e. make_model() and then in update_model() just reference the make_model() help file?

For example see ?plot.ecdf(). Also this could potentially be a solution to the plot issue @macartan mentioned above. I.e. users can always come back to ?make_model() help file to review plot.causal_model() arguments.