Allegro.cc - Online Community

Allegro.cc Forums » Off-Topic Ordeals » Pretentious documentation award

This thread is locked; no one can reply to it. rss feed Print
Pretentious documentation award
Peter Hull
Member #1,136
March 2001

Sometimes I think documentation writers get a little carried away. How about this:

Quote:

An image encoded as part of a file or stream may be thought of extending out in multiple dimensions: the spatial dimensions of width and height, a number of bands, and a number of progressive decoding passes. This class allows a contiguous (hyper)rectangular subarea of the image in all of these dimensions to be selected for decoding.

I just wanted to load a bitmap file, not fall deep into philosophical reflection about contiguous hyper-rectangular subareas. (bonus marks if you know which language's standard library this came from)

Other examples include DARCS which, if memory serves, asserted some kind of connection between diffs and quantum mechanics. Oh, and anything to do with Haskell ;)

What are your favourites?

Chris Katko
Member #1,881
January 2002
avatar

I can't think any off the top of my head, but yeah, I always look down on anyone who uses word fluff for the sake of patting their ego on the back.

-----sig:
“Programs should be written for people to read, and only incidentally for machines to execute.” - Structure and Interpretation of Computer Programs
"Political Correctness is fascism disguised as manners" --George Carlin

Mark Oates
Member #1,146
March 2001
avatar

I need to do this in my own docs. 8-)

--
Visit CLUBCATT.com for cat shirts, cat mugs, puzzles, art and more <-- coupon code ALLEGRO4LIFE at checkout and get $3 off any order of 3 or more items!

AllegroFlareAllegroFlare DocsAllegroFlare GitHub

Niunio
Member #1,975
March 2002
avatar

I use to write long comments in my code (as well as long identifiers). It helped a lot to understand my own code when I want to modify it.

In my last job I was prone to criticise the design my boss demanded to use, demonstrating why it wasn't appropriate. May be I should read it again and write an essay...

-----------------
Current projects: Allegro.pas | MinGRo

furinkan
Member #10,271
October 2008
avatar

Pretty sure most of my comments are just sarcastic remarks and pointing out the obvious.

Polybios
Member #12,293
October 2010

I think someone was bored.

Peter Hull
Member #1,136
March 2001

Sorry, I was in a grumpy mood yesterday. I re-read the Darcs docs - to be fair, the quantum mechanics part is a bit tongue-in-cheek. Also it is written in Haskell, so arguably never stood a chance.

Elias
Member #358
May 2000

I think I may have read that hyper-rectangular sentence, I guess it's something as trivial as libpng. I never considered it that strange a choice of words, rectangular -> cubic -> hyper-rectangular, so just another way of saying "more than 3 dimensions" :)

--
"Either help out or stop whining" - Evert

Bruce Perry
Member #270
April 2000

You think that's bad? Ever tried to decipher a paper about computer vision?

I now know such terms as

  • Lie group (nothing to do with cake)

  • Annealing particle filter (nothing to do with hot metal sparks)

  • The Wiener process noise (sorry, this just sounds stupid)

One could argue that the documentation you're dealing with just needs a note at the start stating that the class offers partial image decoding functionality, and if you just want to decode images, look in such and such a place. Or that there should be a more helpful table of contents before you get that far, or that there should be some tutorials or some effort to list the basic functionality more prominently than the advanced stuff. Still, I didn't find their description too pretentious given what functionality they're actually offering ;)

--
Bruce "entheh" Perry [ Web site | DUMB | Set Up Us The Bomb !!! | Balls ]
Programming should be fun. That's why I hate C and C++.
The brxybrytl has you.

Niunio
Member #1,975
March 2002
avatar

Elias said:

I think I may have read that hyper-rectangular sentence, I guess it's something as trivial as libpng. I never considered it that strange a choice of words, rectangular -> cubic -> hyper-rectangular, so just another way of saying "more than 3 dimensions" :)

I prefer tesseract.

-----------------
Current projects: Allegro.pas | MinGRo

Chris Katko
Member #1,881
January 2002
avatar

My new 3-D engine only supports hypo-tesseracts.

-----sig:
“Programs should be written for people to read, and only incidentally for machines to execute.” - Structure and Interpretation of Computer Programs
"Political Correctness is fascism disguised as manners" --George Carlin

Elias
Member #358
May 2000

My new 3-D engine only supports hypo-tesseracts.

Would that be penteracts or hexeracts then? I think the original documentation implies that it can deal with all of those.

--
"Either help out or stop whining" - Evert

Bruce Perry
Member #270
April 2000

I think a hypo-tesseract is a cube, square, line or point :)

--
Bruce "entheh" Perry [ Web site | DUMB | Set Up Us The Bomb !!! | Balls ]
Programming should be fun. That's why I hate C and C++.
The brxybrytl has you.

Arthur Kalliokoski
Second in Command
February 2005
avatar

Wouldn't it be a 4D engine then?

They all watch too much MSNBC... they get ideas.

Gideon Weems
Member #3,925
October 2003

I think a hypo-tesseract is a cube, square, line or point :)

Hypopotamus.

Go to: