> Many believe that MDN should be where user-facing API documentation lives.
Who's the user here? Add-on developers, Gecko developers, or something else? It sounds like maybe you mean Gecko developers? I really don't think the task of Gecko developers, casual or otherwise, would be made substantially easier if documentation about more of our classes was available on MDN, in the form an automated from-source translation. Easy search of and navigation around our source is key to effective Gecko development. But once that, you can quickly access the relevant in-source docs. So inasmuch as you think it's hard for casual developers to use our in-source documentation, I think it would be helpful to focus on the question of how to improve upon tools like MXR and DXR. (Personally, I use grep plus a simple vim plugin [1] which lets me go straight to a grep result within vim for 98% of my searches. I don't know how anyone manages to use anything less-streamlined on a regular basis. :) > So, I guess what I'm asking for is for MDN to deploy two features: 1) a > publishing API 2) read-only pages. Then, we need > some middleware that synchronizes the source tree to MDN. Of course, we > should probably have discussion on whether > this is a good idea first. It's hard to see how this would be useful in practice, since comments in source will make very poor wiki articles (and it sounds like you'd agree that we shouldn't put wiki formatting into our comments). I think you'd end up with something which effectively embeds many MXR pages into MDN. At which point we haven't really created something more useful than MXR. But this is all quite off-topic for this thread, I think. [1] https://github.com/jlebar/search-plugin > MDN certainly has a better user experience than foraging around > mozilla-central (especially if you are just a casual developer). If I'm a > casual extensions developer, I much prefer browsing MDN to searching for > files in the tree and looking at source code. Why are you making me look at > source code when all I need to know is how the API works?! Good > documentation alleviates the need to look at source code. User experience > matters and developers are users too. We are right in wanting to promote a > better user experience/MDN for documentation. > > The problem with MDN is it isn't integrated with the source tree in any way > AFAICT. So, as a developer, I have a conflict. Do I write great docs in the > tree? If so, I have to manually replicate those on MDN. And, I have to > remember to do this every time I change docs. This takes a lot of effort, > especially when you consider czars don't run every module and changes creep > in from people not as stringent about docs as you. Alternatively, I take the > lazy road and don't bother synchronizing docs to MDN. Or, I'm ignorant about > the existence of docs on MDN and don't know they need to be updated. So, > either it takes me/developers a lot of extra work to ensure all the docs are > up to date. Or, developers who don't want to or can't afford the time to > source forage lose out because the docs don't exist or aren't up to date. > This system is set up for failure. > > I'd argue things would be in a much better state if in-tree docs were pushed > to MDN or some other read-only docs site. I'm arguing for the docs to live > in the tree because from my experience the closer the docs are to the things > they describe (typically source code), the higher the likelihood that they > are up to date because of their higher visibility to developers. At some > point you'll want to consider higher-level docs in a medium that is easier > to edit than our source tree. I'm not sure where to draw that line. > Certainly things like IDL and class documentation should be pulled from > source and read-only. But, that line get blurry pretty fast. > > So, I guess what I'm asking for is for MDN to deploy two features: 1) a > publishing API 2) read-only pages. Then, we need some middleware that > synchronizes the source tree to MDN. Of course, we should probably have > discussion on whether this is a good idea first. > > > On 9/14/12 2:56 PM, Justin Lebar wrote: >> >> We've been adding a lot of new code lately, particularly as part of >> B2G. But we have not been adding high-level in-source documentation >> along with that code. >> >> The result is that it's becoming increasingly difficult to find one's >> way around our code. >> >> To be clear, my beef here isn't so much with a paucity of nitty-gritty >> comments in implementations about why we do something a particular >> way, but with the lack of higher-level comments in headers, IDL files, >> and JS services explaining what a class or interface is used for, how >> it interacts with other classes, and non-obvious particulars of the >> API it exposes. >> >> I don't want to pick on any specific examples too much, because I >> think the problem isn't specific examples but rather the general >> culture that it's OK to check in headers and interfaces without any >> comments. But lest you think I'm imaging this problem, I'll point to >> a few files that happen to be on my mind at the moment: >> >> * nsISettingsService is a device-settings API used in B2G. It's not >> at all clear to me how to correctly use this interface. Some >> questions I have include: What is the optional aMessage argument on >> set() for? Are the settings locks re-entrant? What can I set a >> setting to (they're jsvals)? Unfortunately there are no comments on >> the interface. >> >> * What's the difference between mozilla::system::TimeSetting and >> mozilla::dom::time::TimeManager? Even if I gave you the header files >> (which don't have any comments), I don't think it would be >> particularly clear what's going on. >> >> Again, the problem isn't these examples specifically -- the vast >> majority of B2G work I've seen has been un- or severely >> under-commented. >> >> I propose here that reviewers and super-reviewers should require that >> new code be appropriately commented, just as we require that new code >> be appropriately formatted. (We seem to be quite good at enforcing >> the latter, even though I hope we can agree that comments are, at a >> minimum, as important as formatting. Maybe we should put something >> about commenting in the style guide. :) >> >> "Appropriately commented" is obviously up to individual >> interpretation. But I think at a minimum, interfaces and classes >> defined in header files should be preceded by a sentence or two >> explaining their purpose and perhaps how they interact with other >> pieces of code. Additionally, I'd say that methods and arguments in >> an API (in a .idl, .ipdl, .h, or .js file) should be documented to an >> extent which would allow a programmer of average skill (for Mozilla) >> to correctly use the API without reading the implementation. That may >> mean that none of the methods on a particular API get any comments, >> which is totally fine by me. >> >> I really hope this isn't controversial. Again, the point isn't to go >> crazy with comments; they are merely a means to an end. >> >> -Justin >> _______________________________________________ >> dev-platform mailing list >> dev-platform@lists.mozilla.org >> https://lists.mozilla.org/listinfo/dev-platform >> > _______________________________________________ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
