next »

[rogerlevy]

The engine is written in Forth.  Which isn't supported.

Oh, if only Doxygen were more language-agnostic ... and if only I liked docs generated by Doxygen...  

Also - NOT a big fan of doc-laden source code.  I like my code tight and compact.  I might write my own code editor one day that can keep docs associated with functions in some kind of database without actually putting it in the source you have to work on... but not yet.

[14113]

I'm gonna second (or third or whatever) the cplusplus documentation, its pretty awesome, and has pretty good descriptions of stuff.

I'll also recommend the processing documentation http://processing.org/reference/ and the (similarly constructed, and laid out) openframeworks documentation http://www.openframeworks.cc/documentation.

The processing docs are particularly good, as they give small examples of using each item. OpenFrameworks has less information about each thing, but they are (in my opinion) better laid out when you get down to the individual items.

[Gimym TILBERT]

Blitz3D

F1 (show syntax) F1 again (show description and exemple in a new tab + link that open the exemple in a tab for execution + link for website with up to date description and comment from the community + link toward community driven exemple and inscription + link toward last installable version of docs)

You can't beat that

You can always access them in tab and they are ordered by topic and in alphabetical order too + topic or alphabet neatly collapse for better readability.

[rogerlevy]

Progress on my docs...

http://code.google.com/p/tengoku-engine/wiki/CoreReference

The "core" part is like 2/3 done, this was after a couple hours of work ... just need to do  the classes ...

I'm wondering how terse is too terse ... in my opinion having too read too much is worse than not having enough information ... I'm learning how to write effective docs so if anyone can give me comments on my work so far that would be so nice.

[14113]

Maybe some examples as well? they don't have to be on the same page, they could be somewhere else, but it would still be helpful to people.

[mcc]

I was very impressed with the documentation for Apple's Cocoa and also Qt. Basically anything with javadoc/doygen style documentation WHERE THE JAVADOCS ARE EXHAUSTIVELY FILLED OUT AND NOT JUST A METHOD LISTING is great. Of course this sorta assumes an OO framework is being used.

I have never been impressed with MSDN documentation, however, there is a particular thing I really really like about the .NET documentation. If you are looking at the documentation for, say, System.Xml.XmlReader in .NET, there is a little navigator up at the top showing all versions of the .NET API that that class is present in and allowing you to switch quickly between versions. So I can immediately tell: Okay, this is how far back the feature goes; and if I'm looking at the "wrong" version I can get to the one I actually want to know about quickly. I wish all API docs had this feature, the python docs especially suffer for lack of it (and the Python docs they sometimes move things around between doc versions, so if you find yourself accidentally looking at the 2.2 version of something in the docs you can't just edit the url to say /Py3k/ and assume you'll find it ).

[rogerlevy]

Maybe some examples as well? they don't have to be on the same page, they could be somewhere else, but it would still be helpful to people.

This sounds like a great idea, but thinking of examples is really hard! 

[george]

I might write my own code editor one day that can keep docs associated with functions in some kind of database without actually putting it in the source you have to work on... but not yet.

http://webpages.charter.net/edreamleo/front.html

Or if you use Emacs, org-babel.