Principles of documentation (was: Python Documentation Blows!)

Discussion in 'Python' started by Cameron Laird, Apr 3, 2004.

  1. In article <c4dpro$5vg$>,
    Josiah Carlson <> wrote:
    .
    .
    .
    >better. Maybe it was that year of only really knowing C and C++ that
    >makes the difference, but I've never had issue with the wxWidgets
    >documentation.
    >
    >While I prefer Python's name with description later, having the type of
    >input and output from the function call given in the function definition
    >is convenient. Programming with a language that is static typed may be
    >a pain in the ass, but it is damn convenient when you are looking at
    >documentation. Even though wxWidgets class definitions can have huge
    >initialization argument lists, generally you can be sure of what you are
    >supposed to pass into something, and what you can expect in return.
    >
    >
    > - Josiah


    We're different--always interesting. As a heavy consumer and
    producer of documentation, "having the type .. in the function
    definition is convenient" intrigues me. Clouding my thoughts
    a bit is C's wimpy type system ('love the language, 'recognize
    its limits). Your proposition sounds to me much like what we
    used to believe about compile-time syntax checking, versus
    more robust and application-specific unit tests.

    My preliminary reaction, therefore: yes, indeed, type declar-
    ations are important, Python documenters should be particularly
    careful always to specify them explicitly, and, if anything,
    Python has the chance to improve on the standards C and C++ set,
    as its typing is stronger.
    --

    Cameron Laird <>
    Business: http://www.Phaseit.net
     
    Cameron Laird, Apr 3, 2004
    #1
    1. Advertising

  2. Re: Principles of documentation

    > We're different--always interesting. As a heavy consumer and
    > producer of documentation, "having the type .. in the function
    > definition is convenient" intrigues me. Clouding my thoughts
    > a bit is C's wimpy type system ('love the language, 'recognize
    > its limits). Your proposition sounds to me much like what we
    > used to believe about compile-time syntax checking, versus
    > more robust and application-specific unit tests.


    Goodness, please don't lump me with the compile-time syntax checking
    zealots *wink*. I'm talking about convenience in documentation of C/C++
    functions; it tells you what you /should/ be passing in. No more, no
    less. I find reading such type signatures to be quicker than linguistic
    descriptions of the passed arguments.

    One really nifty thing about decorators (PEP 318) is that people will
    have the option of strong and dynamically typed polymorphism, but the
    drawback is that we may get some C++ or Java programmers who use it for
    everything, even when it is not necessary or detrimental.


    > My preliminary reaction, therefore: yes, indeed, type declar-
    > ations are important, Python documenters should be particularly
    > careful always to specify them explicitly, and, if anything,
    > Python has the chance to improve on the standards C and C++ set,
    > as its typing is stronger.


    Agreed.

    - Josiah
     
    Josiah Carlson, Apr 3, 2004
    #2
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Tom Beretvas

    Netframework 1.1 install blows up

    Tom Beretvas, Jul 21, 2005, in forum: ASP .Net
    Replies:
    3
    Views:
    694
    Tom Beretvas
    Aug 12, 2005
  2. Gary

    I.E. blows after running my app

    Gary, Apr 2, 2004, in forum: ASP .Net
    Replies:
    1
    Views:
    314
    Alvin Bruney [MVP]
    Apr 3, 2004
  3. Amy B
    Replies:
    2
    Views:
    559
    Guest
    Feb 25, 2005
  4. Jorge Godoy

    Re: Python Documentation Blows!

    Jorge Godoy, Apr 1, 2004, in forum: Python
    Replies:
    2
    Views:
    274
    Peter Hansen
    Apr 1, 2004
  5. Terry Carroll

    Re: Python Documentation Blows!

    Terry Carroll, Apr 16, 2004, in forum: Python
    Replies:
    2
    Views:
    278
    Roger Binns
    Apr 18, 2004
Loading...

Share This Page