After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 574573 - JavaScript code documentation
JavaScript code documentation
Status: RESOLVED OBSOLETE
Product: gnome-shell
Classification: Core
Component: general
unspecified
Other Linux
: Normal normal
: ---
Assigned To: gnome-shell-maint
gnome-shell-maint
Depends on:
Blocks:
 
 
Reported: 2009-03-08 18:21 UTC by Sander Dijkhuis
Modified: 2016-11-11 11:53 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Sander Dijkhuis 2009-03-08 18:21:30 UTC
In the mailing list, I proposed using Code Illuminated for documenting the JavaScript code:
http://mail.gnome.org/archives/gnome-shell-list/2009-March/msg00001.html

I've now added all script files to the documentation. The panel.js documentation has changed a bit, and appDisplay.js has been adjusted. The other files are not fully documented or adjusted yet, but have a header added to them because otherwise they wouldn't show up. The result can be viewed at:
http://sander.github.com/tmp/gsdoc/documentation.html

I'm working in a branch hosted at Github:
http://github.com/sander/gnome-shell/tree/ci-doc

Currently, the documentation.html hyperlinks to a specific SVN revision of Code Illuminated at googlecode.com. I don't use the 'head' revision to ensure compatibility. When CI releases a compatible update, the revision number would need to be updated in documentation.html.
Comment 1 Owen Taylor 2009-03-16 17:55:08 UTC
Here's what I like about what you have so far
=============================================

The general idea: I like the idea of a code browser that uses formatting, hyperlinks, etc, to enhance the ability to read the code and figure out what is going on.

The AJAX client side formatting: It's distinctly need that nothing needs to be generated in the build process.

The wiki markup: It's lightweight, it doesn't detract from the ability to read the code as code.

Here's what I feel is missing
=============================

Readability: A big one. :-) If I zoom the page in enough far enough to be able to read the code on the right comfortably, the text on the left is ridicuously large. If this is meant to be a code browser, and not API docs extraction, then the code is not secondary to the comments. Comments are there to illuminate what the code is doing, to describe contracts between different sections of code, and where appropriate to give a high-level overview. Docs should never duplicate what can be said better in code. (I'm maybe a little skeptical that the two column layout is workable - and think it might work better with at least section headers and major comments inline with the code. I could see minor descriptive comments being positioned off to the side. But maybe the two olumn layout could be made with adjustments to font size and relative widths.)

Syntax-highlighting: Again part of the code-browsing aspect; code is easier to read and understand when syntax highlighted.

An understanding of code structure: Having to add wiki-markup to mark each class and function is a bit cumbersome. Having undocumented functions not show up at all could be confusing. The code describes itself what the functions are, what the classe are, it would be nice if the tool could pick that up.

Navigation: Having an index for each page would make easy to jump to particuar functions. (Maybe up top, maybe a fixed-position div that stays in place while scrolling, different ways it could be done.)

Cross-references: A hard one given the nature of Javascript, but being able to jump directly from where a method is called to the docs of that method would be a huge win for a code browser. Possible idea that avoids type inference: When someone clicks on a method name, show a menu of all methods with that name in the project. Many method names will be unique.

The Bottom Line
===============

None of the "missing" items above are in any way blockers, well, except maybe for the font size issue; my basic question is whether you feel that (through your own work or through uptream Code Illuminate changes), there is a good chance of things evolving toward a better code browsing experience. If that's the case, I'm happy to land the changes and see where things go. If on the other hand, you don't think Code Illuminated is going to evolve much, then I'd rather hold off.

In term of details, the only thing I might want to see changed before landing this is I don't really like linking out to with the svn links, even to fixed versions. I'm not sure I have a great rationale for that, but in general terms, I don't think making a web site depend on external resources works that well. I'd rather just check in the fixed versions into a subdirectory of our git repository and make things standalone. (Maybe use a minified jquery? I don't know the size difference in practice.)
Comment 2 Bijan Binaee 2012-01-11 09:03:43 UTC
please check your link some of them are mot work
Comment 3 André Klapper 2012-01-11 09:54:22 UTC
(In reply to comment #2)
> please check your link some of them are mot work

They all work perfectly for me. If you have problems you should ALWAYS be specific and exact when describing them, instead of "some stuff doesn't work".
Comment 4 Bijan Binaee 2012-01-11 10:40:44 UTC
ok see http://student.science.uva.nl/~sqdh/gs-mockup/doc/index.html
 and http://sander.github.com/tmp/gsdoc/documentation.html

they open for me blank i also use a proxy for ensure that 
sorry for my bad report(In reply to comment #3)
> (In reply to comment #2)
> > please check your link some of them are mot work
> 
> They all work perfectly for me. If you have problems you should ALWAYS be
> specific and exact when describing them, instead of "some stuff doesn't work".

ok see http://student.science.uva.nl/~sqdh/gs-mockup/doc/index.html
 and http://sander.github.com/tmp/gsdoc/documentation.html

they open for me blank i also use a proxy for ensure that 
sorry for my bad report! but plz use f5 to ensure they are not in your browser cache!
Comment 5 André Klapper 2012-01-11 10:47:27 UTC
Both work fine for me so it's likely an issue with your connection.
Comment 6 Sander Dijkhuis 2012-01-11 11:05:00 UTC
Both pages also work well on my system, in both Firefox and Chrome.

About the bug. There have been no updates to Code Illuminated since June 2009. After Owen’s review I had started working on layout changes to address the font size, syntax highlighting and in-page navigation:

Source: http://code.google.com/p/code-illuminated/source/browse/?name=layoutchange
Example: http://code-illuminated.googlecode.com/hg-history/layoutchange/index.html#docs/docs.js

However, this was never finished. I now also agree that the two-column layout might not work out well for GNOME Shell. I will not continue this work anytime soon myself, and suggest looking for another solution than Code Illuminated.
Comment 7 Allan Day 2016-11-11 11:53:58 UTC
This is an old bug and there haven't been updates for a while, so I'm closing as obsolete. Feel free to reopen if it's still relevant.