On Wed, Feb 6, 2019 at 2:25 PM Kris Maglione <kmagli...@mozilla.com> wrote: > >* Perhaps a link (or multiple links) to MDN docs we already > >have on XPCOM components - which may provide an introduction as > >to what they are, when and why they’re used, etc. > > I'm not sure this is a good idea. Docs about Gecko internals on > MDN are generally deprecated, and the ones about XPCOM are > obsolete to the point of being useless.
+1, just say no to internal docs on MDN. Documentation that we can auto-generate from the source code directly is preferred over standalone docs, although even in the latter case it's much better to have this live alongside the source code so we know which revision of m-c it applies to. In both cases https://firefox-source-docs.mozilla.org/ should always be used for Firefox internals, and MDN only for web standards and standard-ish things like WebExtension APIs. Speaking of auto-generation, could some/all of the code blocks in https://searchfox.org/mozilla-central/rev/e00ea598e52bbb35f8c45abf9c2eade17962bb5e/build/docs/defining-xpcom-components.rst be generated via autodoc from https://searchfox.org/mozilla-central/rev/e00ea598e52bbb35f8c45abf9c2eade17962bb5e/xpcom/components/gen_static_components.py ? I suspect it'd increase the readability of that file and make it easier to modify if those bits were separated into a Python class anyway. Note that I don't have particularly strong feelings about this, if you think it's easier to keep the docs separate and/or don't expect to change it much in the future then that's fine too. > I'm also a bit leery about mentioning old coding styles in docs > like this, since those kinds of mentions tend to stick around > long after everyone has forgotten that style ever really > existed... Agreed, we're still dealing with fall-out from people getting confused about old add-ons documentation and snippets etc. that look official since they are on MDN. An even better example where this causes confusion over internals is https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Observer_Notifications - that would be a great candidate for auto-generating from source code. > >* An example of ‘old style’ vs. ’new style’ xpcom definition, > > perhaps even a ‘good’ vs. ‘bad’ - but there’s a negative > > connotation there, which may not be preferred. > >* A full example (prolly on a second page would be best), which > > showcases the discrete steps to get from zero to hero. Err, I > > mean new component. > > > >I’m suggesting all this extra work, because I think it will > >actually save you a lot in the future; rtfm is a very simple, > >yet powerful response to all the queries you’re gonna get. > > Again, I'm not sure the linked doc is really the best place for > such things, since the doc is meant to be permanent, and it > would get dated fast. > > I can give examples in this thread, if you think it would be > useful. But given that I've already converted (or have pending > patches to convert) pretty much all of our old-style > registrations, it wasn't clear to me that it would. I would like to see examples in this thread. It'll be as easy to link folks to the mailing list archive, and it'll be clearer that it's ephemeral since it's a mailing list from a specific time period. Thanks again for making this change :) _______________________________________________ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
