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)

enhancement

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
Blocks: 57237
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?
Assignee: brendan → endico
Keywords: patch, review
See bug 61311 for some information that should be in an INSTALL file.  (run
./regxpcom and ./rechrome when installing nightlies as root)
Dawn,
Brendan,
Chris,
can one of you drop a word of wisdom here, please? Who should own this?
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
Thanks, Santa Claus. You rock!
Ulp, only one day of Christmas left....

/be
Maybe the easter-bunny will enjoy reviewing a 20 lines README file?
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
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.
Please no README files. Make it readme.html or something. README files are not 
windows friendly.

Depends on: 60701
Depends on: 59137
Depends on: 45863
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
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
Whoops, wrong bug!  Dammit, bugzilla tricked me.  Sorry for the spam.

/be
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
Disowning.

/be
Assignee: brendan → nobody
Status: ASSIGNED → NEW
moving to default owner, so it's on someone's radar.
Assignee: nobody → endico
*** Bug 72037 has been marked as a duplicate of this bug. ***
Depends on: 159248, 177341
No longer depends on: 60701
Please add bug 136258 to this bug's dependencies.
As requested, adding bug 136258.
Depends on: 136258
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.
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.
-> Josh
Assignee: endico → joshuaheidenreich
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
Josh: please use README (allcaps, for better ls-sorted output), and use .html
(not .htm) for text/html file suffixing.

/be
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.
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.
Component: Mozilla Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
QA Contact: imajes → doc-request
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.
Assignee: josh.sickmate → nobody
Component: Documentation Requests → General
Product: Mozilla Developer Center → Core
QA Contact: doc-request → general
Severity: normal → S3
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.

Attachment

General

Created:
Updated:
Size: