[api-documenter] don't generate separate files for methods and members

[spion]

I don't know if its possible, but it would be better if api-documenter's markdown documenter generated a more sensible structure:

• a directory per package - no prefix for the markdown file name
• only classes, functions, interfaces/types and namespaces get a separate file
• methods and members are included in the class / interface / type document

[rudolf]

I like what you did in dubzzz/fast-check#343 (hosted version: https://dubzzz.github.io/fast-check/#/2-API/fast-check/Arbitrary?id=chain). I think having the class methods/properties in the same file creates a flatter structure which is easier to navigate and cross-reference.

I'd say it's worth submitting a PR to discuss making this the default behaviour for api-documenter.

[octogonz]

I apologize that it's been a couple weeks without a response. (All my free time has been going into writing the 50+ pages of docs for the overhauled api-extractor.com web site, which I hope to publish tonight. :-) )

it would be better if api-documenter's markdown documenter generated a more sensible structure

This is a good idea. We would definitely accept a PR that adds this feature.

I'd be interested to hear whether people think we should change the design so that this is the only option, or if the current behavior is useful enough that we'd want to provide both options (e.g. via a configuration switch). BTW the current URL structure is historical; it supported an earlier MS Office documentation system that has since been retired.

[spion]

Personally I don't find the current layout useful, but lets see what others have to say. I am still trying to refine what the best variant would be for me. For example, I don't have an idea how to represent functions with multiple different overloads, but it seems best that they end up in a single file too...

[octogonz]

I think having the class methods/properties in the same file creates a flatter structure which is easier to navigate and cross-reference.

In the past we had several debates about this with different teams. The conclusion seemed to be:

• If you write long detailed comments for each member, then you prefer a separate page for each method (and maybe also each property)
• If you only write a sentence or two, then you prefer to have all the members on the same page. More people are in this group because writing docs takes effort.
• So maybe there should be a choice
• But if you choose wrong and change your layout later, the URLs will change, which breaks hyperlinks for anyone who linked to your site

We also did a survey of popular API reference websites, and found that both approaches are fairly common. I think it just depends how much content you write (and maybe also how many methods you add to a classes).

[spion]

I typically use the Google maps API reference as my benchmark of a well designed API and reference. They tend to cluster methods of the same class, sometimes even multiple related classes together.

In my effort with quickcheck and docisfy above, I rely on the fact that the sidebar provides quick navigation for all the separate methods - so regardless of the length of the document its fairly easy to navigate to the thing you care about. The maps API has a similar scheme, with the in-document navigation displayed on the right hand side.