how do you direct people's attention to the methods that count

[mwhudson]

Especially if the changes I recommended in https://bugs.launchpad.net/pydoctor/+bug/997295 are made, it should be a lot easier to see the public methods of private base classes, without having to be aware that the base class is there or private. It's a bit confusing to have to click into apparently private documentation to see important bits of functionality.

For example, on http://twistedmatrix.com/documents/current/api/twisted.python.filepath.FilePath.html, you can see lots of irrelevant methods (and you would see private methods, if there were any) on FilePath before seeing core functionality like walk() which happens to be defined on _PathHelper.

Maybe the thing to do here is just to emphasize the "implements interfaces" section a bit more and display the whole interface docstring on each method rather than just the somewhat ambiguous "from" link.

---

Imported from Launchpad using lp2gh.

• date created: 2012-05-09T20:03:05Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/997302

[mwhudson]

(by mwhudson) Yeah, this is hard. I think I'd like to frame it a bit as "how do you direct people's attention to the methods that count" rather than anything to specifically to do with privacy.

It seems to me the dilemma is that when looking at a class that is derived from a base class, you might either want to understand the entire class as a thing -- in which case, just listing all methods in one big table makes sense -- or you might want to understand how this class differs from its base class -- in which case what pydoctor does now makes sense. Of course, if the base class is private, then presumably you're just inheriting for implementation only, and the former option makes sense.

FWIW, there is an option in pydoctor (inexplicably called --html-use-splitlinks) that generates both "one big table" and "per base class" tables and has some simple js to flip between them.

There is the also the issue of picking out interesting methods from a sea of detail. One thing we could do is highlight the methods that implement a method from an interface somehow?

I'll try to grab you on IRC to talk about this tomorrow.

[mwhudson]

(by exarkun) I'm confused about the state of this bug. http://twistedmatrix.com/documents/12.3.0/api/twisted.trial.unittest.SynchronousTestCase.html shows the methods SynchronousTestCase inherits from _Assertions. I don't see any obvious UI for flipping between this display and another, so it doesn't seem like --html-use-splitlinks is in use here.

[mwhudson]

(by mwhudson) Jean-Paul Calderone

I'm confused about the state of this bug.

The state of this bug is that I don't really know what the best way forward is.