search

jsdoc2md / dmd

The default output template for jsdoc2md
MIT License
39 stars 49 forks source link

How stable is the partial hierarchy for overriding purposes? #19

Closed mhelvens closed 9 years ago

mhelvens commented 9 years ago

I've been making thankful use of the ability to override partials. I override partials that are included by others, and I override partials that include others.

By explicitly allowing this, you have essentially made the entire partial hierarchy part of the public API of dmd. I'd just like to make sure: can I be confident that my overrides will continue to function when I update dmd?

It must be tempting for you to refactor this stuff now and then. But strictly speaking, whenever you do this, it is a breaking change and according to semantic versioning you'd need to increment the major version number.

What is your policy w.r.t. this issue? Thanks!

75lb commented 9 years ago

you’re absolutely right, the dmd partial hierarchy is part of the public API so yes, major versions will be updated on breaking change.. and yes, a massive refactor of the partials is imminent as it’s just too complex for a regular user to quickly find which partial needs editing.. Also, the plugin-creation workflow is currently too complex/slow.

i have a half-finished dmd “playground” which will make understanding and overriding dmd easier, but it’s probably a month or two away..

so don’t worry, i’m aware and will be careful.. if any future release does break anything, please let me know asap..

mhelvens commented 9 years ago

Thanks! Very clear.

75lb commented 9 years ago

you're welcome.. one other thing - if your overrides improve the look/feel of the generated docs let's bundle them up as a plugin, for others to enjoy.. or pull them in the to main project! Either way, we can credit you on the main readmes.. cheers :)

mhelvens commented 9 years ago

I'm currently still playing around with them, but there are indeed some features that would be nice in the main project. For example, I'm currently working on a way to skip the full body of inherited properties, and to instead provide a list of hyperlinks to the originals.

I'd be happy to contribute. But if you're planning a major refactoring, I guess I'd better wait until after.

75lb commented 9 years ago

I'm currently still playing around with them, but there are indeed some features that would be nice in the main project. For example, I'm currently working on a way to skip the full body of inherited properties, and to instead provide a list of hyperlinks to the originals.

this is the intended default behaviour - something is amiss here.. i will take a closer look at your project / jsdoc-documentation later.. although, that might be hard as i left my laptop on the tube a couple of days ago! still pissed about that.. but i will look asap.

I'd be happy to contribute. But if you're planning a major refactoring, I guess I'd better wait until after.

no need to wait - your contributions will be invaluable at any point.. any contribution received against master will still be factored into development branches, if they exist..

mhelvens commented 9 years ago

this is the intended default behaviour - something is amiss here.. i will take a closer look at your project / jsdoc-documentation later

Ah, this doesn't manifest in the link I gave you. You can look at the last revision of delta.js instead. For example, the DeltaJs#Delta#applicationCondition property is inherited by a whole bunch of Delta subclasses, and seems to be fully repeated each time.

no need to wait

OK. I'll see what I can do. Would you prefer contributions in the form of a plugin, or a pull request to the main repo?

75lb commented 9 years ago

Ah, this doesn't manifest in the link I gave you. You can look at the last revision of delta.js instead. For example, the DeltaJs#Delta#applicationCondition property is inherited by a whole bunch of Delta subclasses, and is fully repeated each time.

ok, thanks.. will take a deeper look asap..

OK. I'll see what I can do. Would you prefer contributions in the form of a plugin, or a pull request to the main repo?

we’ll see.. if we think the updates are something all users would prefer, then let’s pull it in.. otherwise, it’s probably safer to start with an optional plugin.. if use of the plugin becomes “defacto” then yes, it will definitely get pulled in..