rjbs
Confusing doc layout (rt52876)
https://rt.cpan.org/Ticket/Display.html?id=52876
I gave rjbs my impressions from my first encounter with App::Cmd. Its in his chat log. He said to bug it. Here it is.
Michael Schwern: Got a moment to hear App::Cmd feedback?
rjbs: sure thing
Michael Schwern: So I sat down to write something like "gitpan clone
if ($opt->verbose) { ... } rjbs: $args is an arrayref of all the stuff left over rjbs: so: myapp cmd --verbose --protocol tcp myfile might leave $args = [ 'myfile' ] rjbs: so the validate args there is saying: before you go any further, if the user said --help, give a help message. Michael Schwern: So this is in addition to Getopt::Long::Descriptive's checks rjbs: yes rjbs: GLD validates switches. Michael Schwern: Ahh, that's not obvious rjbs: validate_args validates what's left over. rjbs: Ok. rjbs: So, I will insert some more documentation above the paragraph beginning "The first two methods" Michael Schwern: I think part of the problem is the App::Cmd page presents itself as "here, its easy!" and then there's a bunch of documentations for lots of methods not mentioned before and little no documentation for the methods already mentioned. Michael Schwern: (man, my fingers are not working) rjbs: nor mine; they're cold Michael Schwern: What is the criterion for the methods documented in App::Cmd? rjbs: They're methods on the App::Cmd subclass. rjbs: or the base class, depending on how you look at it. rjbs: If you write a program "svn" and it has subcommands "commit" and "update" Michael Schwern: Part of the confusion is the "use YourApp -command" cuteness. rjbs: then App::Cmd is the base class of the thing implementing "svn" rjbs: App::Cmd::Command is the base class of the thing implementing "commit' and "update" Michael Schwern: Yeah, that's non-obvious rjbs: the -command thing makes sense, I promise -- but clearly it needs clearer explanation Michael Schwern: It obscures what I'm actually subclassing so I don't know where to look next for documentation. Michael Schwern: That App::Cmd::Setup is documented adds to the confusion rjbs: You don't need to do things that way. rjbs: ugh, I know, that DESPERATELY needs docs Michael Schwern: s/documented/undocumented/ rjbs: Everything Just Works if you just use base. Michael Schwern: Then just use base. rjbs: no Michael Schwern: Then just use parent rjbs: (a) "Everything" was an overstatement; the plugin subsystem wont' work rjbs: (b) it's actually very very convenient to not just use base, once you know how App::Cmd::Setup works rjbs: the plugin subsystem needs to track registered subcommands, etc rjbs: so it needs to use something that will register with the superclass Michael Schwern: You write plugins infrequently enough that I think two lines is ok Michael Schwern: You're optimizing the wrong bit rjbs: It would be two lines in every command, and would have to happen at compile time. Michael Schwern: I thought you said it only effected plugins rjbs: so now it's like BEGIN { PACKAGE->register_with_etc } rjbs: no, it allows plugins to affect command subclasses Michael Schwern: oh, you're doing some sort of wrapper/hijacking of command methods? rjbs: basically, the plugin system allows the command to cause a compile-time import into every command subclass to give things subs rjbs: so you can end up writing: rjbs: sub execute { exit unless prompt_yn("Really???"); rjbs: and prompt_yn is a sub available everywhere because Your::App provides it to all subcommands rjbs: ...but I don't think any of this should really be a big deal. If we go back to the original confusion that occurred, it was "where do I figure out wtf methods I need to write." rjbs: which the tutorial can be clearer about pointing to, as can the main docs Michael Schwern: I would put all the basic user-facing methods in App::Cmd and bury the rest in their respective documentation. Michael Schwern: Also, what's the last argument to describe_options() in Getopt::Long::Descriptive? rjbs: some nightmarish thingI don't remember; I didn't write it :) rjbs: but I can look it up rjbs: all I -ever- do is: Michael Schwern: Oh, that's HDP's fault rjbs: describe_options("%c %o", [...], [...], ...) rjbs: and never the final magic thingy rjbs: I think what I really need is a new document, App::Cmd::Manual rjbs: which is more thorough than ::Tutorial, more a reference rjbs: and covers every class you need to care about rjbs: because I really do wnat each class to document itself normally rjbs: and I can put a big pair of links atop the other classes "SERIOUSLY YOU PROBABLY WANT THE MANUAL" Michael Schwern: Yes Michael Schwern: So my impression at this point is "that's great, uhh, I'm going to hack it together myself" rjbs: ? Michael Schwern: There's just a bit too much hidden magic in App::Cmd. Michael Schwern: For something that I can write in three subroutines and a hash. rjbs: I agree that there are too many underdocumented bits. Michael Schwern: I see where its going though rjbs: I don't agree that you can really do what it does in three subroutines and a hash. ;) rjbs: I do appreciate feedback on where its docs are lacking, and I always try to improve the docs as soon as I get feedback. rjbs: If you have specific questions, I can answer those, to. rjbs: too rjbs: probably what I will do is try to make an outline of Manual.pm this weekend. rjbs: do you think that's a bad plan? rjbs: (Manual.pm) Michael Schwern: I can do what I need in three subroutines and a hash. rjbs: right. Michael Schwern: The argument checking won't be perfect, because it won't be per command. Michael Schwern: OIC, the Getopt::Long::Descriptive documentation is layed out weird. rjbs: Well, is something actually preventing you from using App::Cmd? Obviously, I don't get a dollar if you do or anything. rjbs: How so? I didn't write those docs, nor do I remember how they're written. rjbs: I should look at them. Michael Schwern: Its written almost like its the docs for a program. Michael Schwern: So it has major sections about describe_options() Michael Schwern: But then it has regular function documentation for desribe_options() rjbs: I see. rjbs: Yeah, okay. rjbs: These docs need to be overhauled. Michael Schwern: So if you just search for "describe_options" you'll skip over all the real docs rjbs: I really have barely looked at them, ever, since I had to learn how it worked before they existed (at work). rjbs: yeah, that sucks Michael Schwern: The describe_options() docs point back to the SYNOPSIS, which is not where the meat is. rjbs: ha Michael Schwern: Oh, and the greatest curse of all. "Option specifications are the same as in Getopt::Long" which are a nightmare to find in the Getopt::Long docs! Michael Schwern: Ok, I'm done bitching now rjbs: I was thinking the EXACT SAME THING rjbs: I'm going to summarize them in GLD. rjbs: because I can never find WTF I want in Getopt::Long. rjbs: EVER Michael Schwern: Want me to RT any of this? rjbs: sure! put a ticket in app-cmd, and you can just refrence our chat and I'll be able to pull it out of logs later in case I forget. thanks1 rjbs: btw rjbs: I wrote App::Cmd because I wanted something with good documentation. :-) rjbs: the pre-existing system was... rjbs: http://search.cpan.org/~ALEXMV/App-CLI/
