search

cake-build / website

:earth_americas: The Cake website: https://cakebuild.net
https://cakebuild.net
MIT License
42 stars 228 forks source link

Documentation doesn't show inherited interface methods / properties #187

Open devlead opened 8 years ago

devlead commented 8 years ago

@IanMercer commented on Thu Aug 18 2016

The documentation for IFile doesn't show an Exists property, presumably because that property was inherited from IFileSystemInfo.

The documentation doesn't show that IFile inherits from IFileSystemInfo.

Either the documentation should show the inheritance relationship of IFile to IFileSystemInfo or it should automatically show all the methods and interfaces from any interfaces that are inherited.

daveaglick commented 8 years ago

FWIW, new docs clearly show the inheritance relationship (even considering spitting out a diagram) but do not show inherited members inline in the inheriting type member list right now.

I rather like the way MSDN shows inherited members with a note indicating where they came from. On MSDN, clicking through to the inherited member goes to the details page for the declaring type. I'll circle back around to this issue to see if we can do something similar.

daveaglick commented 7 years ago

The new documentation does show inherited members for types (see http://cakebuild.net/api/Cake.Core.IO/DirectoryPath/). However, inherited members on interfaces still isn't shown.

To be honest, I'm torn about this one. Does an interface that implements other interfaces count as "inheritance"? Should it be shown as such for the docs? What do other docs do? If so, that raises some interesting questions like what if an interface implements two other interfaces with colliding members? What should we show? And which base interface should it come from?

I could use some feedback on this one, both for Cake and in general.

Related Wyam issue: https://github.com/Wyamio/Wyam/issues/408

daveaglick commented 7 years ago

Moved upstream tracking issue to Wyamio/Wyam#480

pascalberger commented 4 years ago

@daveaglick https://github.com/Wyamio/Wyam/issues/408 and https://github.com/Wyamio/Wyam/issues/480 no longer exist. Do you know which is the correct upstream issue?

daveaglick commented 4 years ago

That's a great question! I think the issue numbers are the same in Statiq.Web since the entire repository was moved.

Here's 408: https://github.com/statiqdev/Statiq.Web/issues/408

And that's closed in favor of 480: https://github.com/statiqdev/Statiq.Web/issues/480

These will likely move to the Statiq.Docs repo too at some point once I start working on that and triaging relevant issues over. I think in that case a redirect will be setup since the issues (and not the whole repository) are moving.