search

dlang / ddox

Advanced D documentation engine
MIT License
63 stars 21 forks source link

How to make ditto'd functions appear on the same page? #173

Open schveiguy opened 6 years ago

schveiguy commented 6 years ago

If I have multiple overloads related functions that do similar things, and I want to document them cohesively as a group, then I can ddoc the first one, and write /// Ditto on the next one.

This looks great with ddoc, but not as great with ddox. The ddox version shows each function on its own page, where the ddoc'd parameters may not all apply, and the function description itself can be confusing or weird.

Same thing with aliases to functions (I may ddoc the function and an alias for an alternate name together).

I propose anything that is Ditto'd be put on the same page, and have each symbol that is included link to it. I realize that this requires a huge change to how the pages are generated, so I'm not sure if it would happen, but I think it would read much better.

Edit: I realize now, overloads do get put together.

Further Edit: nevermind, see below.

schveiguy commented 6 years ago

OK, so I see on dlang.org this does work, but for some reason in the build of iopipe docs, it doesn't do this. Changing to a question -- how do I get this to work?

Example:

http://schveiguy.github.io/iopipe/iopipe/stream/IODev.seekAbsolute.html http://schveiguy.github.io/iopipe/iopipe/stream/IODev.seekCurrent.html http://schveiguy.github.io/iopipe/iopipe/stream/IODev.seekEnd.html

These should all be on one page.

s-ludwig commented 6 years ago

The precondition for this to work is that all members of the "ditto" group land on the same output page. For dlang.org that is the case for all symbols that are equal in a case insensitive way. The question is how to approach this for symbols with completely different names. The only proper way that I see is to list all names in alphabetic order somehow (e.g. "IODev.seekAbsolute-seekCurrent-seekEnd.html"). Should be relatively simple to add as an option.

Alternatively, and IMO generally cleaner, I'd really like to have a general grouping feature one day. Those would replace the manually authored category tables in the Phobos docs (e.g. https://dlang.org/library/std/string.html) and might be handy in this case, too. It would still require a somewhat different approach to documenting the functions as it wouldn't be the same as a ditto group.