Something I've been thinking about is that it'd be interesting if we could show our users all of the available public and internal functions for a given contract, including those that are inherited. Looking at the proposed WhitelistedCrowdsale implementation, it's not obvious from the contract code that it includes the interfaces for both the Whitelistee and Whitelister role, and it may be difficult for a user to understand how the contract is supposed to be used when there's no one place where the whole API is shown at once.
I'm not sure though regarding what the best format would be. Do we want to simply list all parents in the docsite (or at the very least, the immediate ones)? Do we want to display the full inheritance tree? Or do we want to straight up list all of the functions, with a note detailing where those are defined?
Good point. I think the API documentation for a contract should have an index of all of its functions, including the inherited ones. The docs for a function would be found in the page of the contract where it is defined, and where the function is inherited there would be a link to that page.
One of the main things I want us to have in the new docsite is crosslinking. It should be very easy (maybe automatic) to include links to other parts of the docs. So the inline docs for WhitelistedCrowdsale could have a sentence saying “this is an extension of Crowdsale”, and have that show up with a link to the right page.
Yeah. What I’m not sure is if those things should be automatic or left to the documentation writer. Automatic would mean that the docsite generator would detect that we call super.foo and add a link. Otherwise, if we make it easy to add (nice-looking) crosslinks, we can leave it up to the inline docs to say e.g. “This function will first perform action X, and afterwards execute the parent Parent#foobar function.”
What do you think? I feel like the manual version will be much better.
Why not both? Ideally, we’d automatically detect all overrides and tag them (a notice saying 'this overrides Parent.foo'), and manual annotations would explain the why.