On 1/23/08, Michael DeHaan <mdehaan@xxxxxxxxxx> wrote: > Michael DeHaan wrote: > > Jesus M. Rodriguez wrote: > >> On Tue, Jan 22, 2008 at 08:44:40PM -0500, Steve Milner wrote: > >>> I was showing func off to a coworker the other day when a question > >>> came up ... > >>> > >>> "This is pretty cool ... where can I get the Code/API documentation?" > >>> The obvious answer is to look at the code ... but why not use > >>> something like epydoc? In past projects it has been helpful and > >>> generally improved the documentation in the code. > >> > >> I agree. Epydoc rocks. We used it with another, no defunct, project. > > > > > > The one thing I don't want to see is a bunch of javadoc-miming, where > > we have stuff like > > > > @param thisIsAFoo -- this parameter is a Foo > > > > which is not kept updated and isn't useful. > > Well, yeah, it might not get updated that is true. We do not have to do that either ... using resttext works ... or even nothing but simple docstrings suffices for epydoc as long as the more indepth information is not needed. > > I would actually like to see more /user/ level documentation built > > first ... code generated docs only go so far. I guess we should figure out how we want our users to read the documentation. Do we want them to look it up online, generate it (resttext in docstrings), read the MODULES/README file, etc.. > > > > > > _______________________________________________ > > Func-list mailing list > > Func-list@xxxxxxxxxx > > https://www.redhat.com/mailman/listinfo/func-list > On a related note... > > modules that take arguments like "all arguments that go through > traceroute" need to be first fixed so they are API based, as opposed to > just passing a bunch of items to a shell prompt. The only other option I see with that is to have very large amount of possible keywords to modules that can take lots of options .... For instance there would be about 12 available keywords to be used with ping ... It makes more sense to do that programaticly, but I'm not so sure it makes sense using func from the command line to do the same thing and *could* end up looking like .... func *.com call networktest ping example.com '' '' 3 5 In the end I'd assume that the programatic view would win since it's probably the bigger use case for func. > Getting away from just being a shell wrapper and screen scrapping > commands should be a continous goal. We haven't been awesome about that > in the past, but now is the time to start doing that. Agreed ... I think (shell wrapping) it's just the easiest thing to do quickly and it is helpful enough to use. If we can deine some useful items (esp from the current user base) that are not shell abstracting we could jump on it quickly. The best ideas out there right now are the system-config items and yum/rpm item that we could start working through. I'll try to pick up on one or more of those modules. > I would much rather see that happen now than adding a bunch of > documentation about how those commands work, especially as we are > starting to see other applications start building themselves > around Func. My group already has a few :-) > Also, writing more (well fleshed out) modules and example apps to > showcase the platform... > > --Michael > > > > > _______________________________________________ > Func-list mailing list > Func-list@xxxxxxxxxx > https://www.redhat.com/mailman/listinfo/func-list > -- "An organisation that treats its programmers as morons will soon have programmers that are willing and able to act like morons only." -Bjarne Stroustrup _______________________________________________ Func-list mailing list Func-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/func-list
