Closed
Bug 59885
Opened 24 years ago
Closed 6 months ago
Need more & better README files in the source tree (keyword: documentation)
Categories
(Core :: General, enhancement, P3)
Core
General
Tracking
()
RESOLVED
WORKSFORME
People
(Reporter: afranke, Unassigned)
References
()
Details
Attachments
(4 files)
Bug 57237 mentions the fear that "Mozilla development is going to belong to an 'exclusive club'". Here is an RFE that could "make it easier for new developers to help Mozilla": Bob McElrath wrote on n.p.m.general in message <news://news.mozilla.org:119/8uk1gu%24le41%40secnews.netscape.com> : > I suggest a systematic, and regular method of including basic documentation > and links in the source tree. This can be as simple as readme's like > xpcom/reflect/xptcall/README (with simply a URL for more docs), or copying > docs from mozilla.org into the source tree (though synchronization could be > difficult -- but it could be done automatically). In addition, there > should be a top level README explaining: > a) what is in each directory > b) what each of the various acronym's are (caps, gfx, l10n, nsprpub, > xpcom, etc...) > c) links to documentation describing various major sub-modules. > And also a top level INSTALL containing the information in > http://mozilla.org/build/. (basically move README/mozilla/README.build to > INSTALL at the top level). > > This time-honored tradition of having README, INSTALL, and even BUGS (link > to bugzilla) and TODO files at the top level is known by most any > open-source hacker. Bugzilla and mozilla.org's docs are not. > > I hope these suggestions are helpful, > -- Bob IMO, a toplevel README would be really useful. It should mention at least: - www.mozilla.org - lxr.mozilla.org - www.mozilla.org/docs - www.mozilla.org/docs/jargon.html (or inline the explanations for the directory names) - www.mozilla.org/build (if there is no separate INSTALL file) - bugzilla.mozilla.org (if there are no separate BUGS/TODO files) Optionally, there could also be other resources a link to - bonsai.mozilla.org (if there is no separate CHANGES file) Who would be the owner of such a toplevel README file? Wrt. the issue of missing READMEs in subdirs, we should probably file separate bugs for each module, assigned to the respective module owners, and make this bug dependent on them. Thoughts? Andreas
Reporter | ||
Comment 1•24 years ago
|
||
Reporter | ||
Comment 2•24 years ago
|
||
Reassigning to default owner for Mozilla Developer Documentation, putting owner/peer of module "toplevel" to cc. Please comment if the above attachment is acceptable as one of the following: mozilla/README.txt mozilla/README/README mozilla/README/mozilla/README Who's the owner of README?
Comment 3•24 years ago
|
||
See bug 61311 for some information that should be in an INSTALL file. (run ./regxpcom and ./rechrome when installing nightlies as root)
Reporter | ||
Comment 4•24 years ago
|
||
Dawn, Brendan, Chris, can one of you drop a word of wisdom here, please? Who should own this?
Comment 5•24 years ago
|
||
I'll work on this over the upcoming holiday break, and may break out dependency bugs for my elves to help fix. Ho ho ho! /be
Assignee: endico → brendan
Reporter | ||
Comment 6•24 years ago
|
||
Thanks, Santa Claus. You rock!
Comment 7•24 years ago
|
||
Ulp, only one day of Christmas left.... /be
Reporter | ||
Comment 8•23 years ago
|
||
Maybe the easter-bunny will enjoy reviewing a 20 lines README file?
Comment 9•23 years ago
|
||
Sure, and I think that README is fine. One nit: why INSTALL before the build link? BUILD seems more like it, or BUILD/INSTALL. /be
Status: NEW → ASSIGNED
Reporter | ||
Comment 10•23 years ago
|
||
INSTALL was simply following the tradition established by other open source software packages where it is usually used as a generic term that includes both build and install instructions. If I had to choose between BUILD and BUILD/INSTALL, I'd prefer the latter.
Reporter | ||
Comment 11•23 years ago
|
||
Reporter | ||
Comment 12•23 years ago
|
||
Reporter | ||
Comment 13•23 years ago
|
||
Comment 14•23 years ago
|
||
Please no README files. Make it readme.html or something. README files are not windows friendly.
Comment 15•22 years ago
|
||
Oh, wait: InsertElementAt overloads its false return value to mean two very different things: out of memory, and index out of bounds. I'm sticking with NS_ERROR_FAILURE for the fixed failure result code. /be
Comment 16•22 years ago
|
||
jband: I'm ok with JS_Save/Restore/DropExceptionState using malloc, I wasn't gonna bloat the API with caller-allocated versions. I think we all agreed that for jsdbgapi.c or other inside-the-engine files, it may pay to inline the fairly trivial guts of these APIs, and specialize away various costs, esp. malloc/free. I didn't bother with that in my jsexn.c patch that added a 'stack' property, of course, because there were lots of costs in that code (the Exception object constructor, but hey, we don't turn OOM into an exception, so memory should be available for other errors-as-exceptions :-) already. I think all is well here, except (now that we're adding JSPD_ flags) the duplication trade-off. I hope I was not hard to deal with in the old days -- I *thought* I catered to your every need! /be
Comment 17•22 years ago
|
||
Whoops, wrong bug! Dammit, bugzilla tricked me. Sorry for the spam. /be
Comment 18•22 years ago
|
||
accepting QA for mozilla developer docs. some of these bugs have been around for a _long_ time. Reporters, would you please review the bugs, see if the issues have been resolved, and close bugs appropriately. I will do a full review of all bugs not touched in one week (8th April). Thanks. </spam>
QA Contact: endico → imajes
Comment 20•22 years ago
|
||
moving to default owner, so it's on someone's radar.
Assignee: nobody → endico
Comment 21•22 years ago
|
||
*** Bug 72037 has been marked as a duplicate of this bug. ***
Updated•22 years ago
|
Comment 22•22 years ago
|
||
Please add bug 136258 to this bug's dependencies.
Comment 24•21 years ago
|
||
I don't mind writing documentation for the lxr source tree, because i think if more of the directories and files had somthing in the 'description' field, it would be so much easier to browse for code.
Comment 25•21 years ago
|
||
I don't mind writing documentation for the lxr source tree, because i think if more of the directories and files had somthing in the 'description' field, it would be so much easier to browse for code.
Comment 27•21 years ago
|
||
when making readme files, should i create a copy of all the directories with the README files in them? For example: /netwerk/readme.htm /netwerk/dns/readme.htm or: netwerk.htm /netwerk/dns.htm any input would be helpful
Comment 28•21 years ago
|
||
Josh: please use README (allcaps, for better ls-sorted output), and use .html (not .htm) for text/html file suffixing. /be
Comment 29•21 years ago
|
||
Josh: LXR has magic support for some strings, if you could make your README(.html) files describe the files in the directory, that'd be great. The "logic" behind it is here: http://lxr.mozilla.org/mozilla/source/webtools/lxr/Local.pm#215 but it's probably easier to just rely on the working examples. In short <span CLASS=LXRSHORTDESC> and <span CLASS=LXRLONGDESC> in README.html will handle directory entries. I think there's a magic way to put descriptions for files, but I can't remember how (you could read the code if you want to). thanks for doing this, we do appreciate it.
Comment 30•21 years ago
|
||
If anyone want's to help, ive made a simple app in visual basic (im not evil, i don't know c++ very well yet & it didn't take me long) for win32 that allows you to put in a short description, long description, related documents (w3c specs, etc), related code & tell it what components the folder relates to. You can email me at joshuaheidenreich@hotmail.com and ill give you it.
Updated•17 years ago
|
Component: Mozilla Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
Updated•17 years ago
|
QA Contact: imajes → doc-request
Comment 31•16 years ago
|
||
This bug appears to be about code documentation in the source tree, rather than documentation on MDC, so I don't think it necessarily belongs in the MDC product.
Updated•16 years ago
|
Assignee: josh.sickmate → nobody
Component: Documentation Requests → General
Product: Mozilla Developer Center → Core
QA Contact: doc-request → general
Updated•2 years ago
|
Severity: normal → S3
Updated•6 months ago
|
Status: NEW → RESOLVED
Closed: 6 months ago
Resolution: --- → WORKSFORME
You need to log in
before you can comment on or make changes to this bug.
Description
•