develooper Front page | perl.perl5.porters | Postings from November 2017

[perl #132422] [PATCH] IO::Socket Documentation

From:
Chase Whitener via RT
Date:
November 26, 2017 08:53
Subject:
[perl #132422] [PATCH] IO::Socket Documentation
Message ID:
rt-4.0.24-9090-1511383146-1428.132422-15-0@perl.org
Hi Everyone,

On removing the shebang and use lines and variable declarations with `my` from the synopsis, I tend to agree with Sawyer's viewpoint. We get lots of people newer to Perl join IRC or other forums and ask questions where they've obviously never seen use strict and use warnings and don't know why their code is failing. Having them be able to copy/paste full examples and run them without error is something I think there's great value in.

On moving some of the alternate constructor examples out of the synopsis and into the constructor area, I'm kind of half-and-half in agreement with you. I'd like to leave them in the synopsis to hopefully make it more clear that IO::Socket somewhat acts as a factory rather than something useful in and of itself. Maybe repeating those examples in the constructor area would be better (also, further constructor docs will be added to the individual ::INET and ::UNIX subclasses once I get to working on those).

On which other methods to show in the synopsis, I completely agree that more should be shown. However, I also figured that more in-depth synopsis examples could be shown in the subclasses of IO::Socket instead.  Once ::INET and ::UNIX are updated in the same style, I could even argue that the synopsis in IO::Socket itself gets trimmed down to just show the methods it makes available. Maybe it'd be better to focus the synopsis on the class functions available to make a subclass, such as ->register_domain() and ->configure()?

It might have been better to hold off on this patch until I'd also worked out the docs for ::INET and ::UNIX, but I didn't want to go through so much effort if people didn't appreciate the doc style change. Chicken/egg problem.

Thanks,
Chase

---
via perlbug:  queue: perl5 status: open
https://rt.perl.org/Ticket/Display.html?id=132422



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About