Re: [PHPLIB-DEV] A framework for web applications From: Teodor Cimpoesu (teo <email protected>)
Date: 01/17/00

Massimiliano Masserelli wrote:
>
> On Sat, Jan 15, 2000 at 07:17:34PM +0200, Teodor Cimpoesu wrote:
>
> TC> 1. I don't see any coding/naming/documenting conventions It would be
> TC> great to have some, so using a simple 10 line perl script to extract
> TC> classes, attributed and methods. (e.g. I really loved python's
> TC> __doc__ attribute)
>
> Have a look at doc/classdoctpl.pl and doc/template.sgml.
>
> Bye.
> --
did,
made
  # classdoctpl.pl < auth.inc
  #sgml2html -s 1 Auth.sgml
and got:
Processing file Auth.sgml
/usr/bin/nsgmls:<OSFD>0:2:0:E: no internal or external document type
declaration subset; will parse without validation
/usr/bin/nsgmls:<OSFD>0:12:12:E: general entity "lowbar" not defined and
no default entity
/usr/bin/sgmlsasp: can't open
`/usr/lib/sgml-tools/dist/sect1/html/mapping': No such file or directory
(sgml-tools-1.0.9-2)
So, is it my version screw up or do I need and older version (as per
README),
but which one?

Second, I'm not such a good Perl reader so I couldn't figure out if it
looks for
some documentation. So I have a
[ PROPOSAL ]
Let's everybody document the classes and functions by the convention
that the very first block of comments after the class/function
declaration
represents it's docstring (I haven't had the occasion to contribute one
yet :-)
but I promise I'll document my code)
This is the same cute thing like in , say, lisp

(defun foo (wop wap)
 "this thingy does nothing"
  (values 1,2,3))

or, python

 def foo(wop,wap):
  """ this looks like a doc strings"""
   return (1,2,3)

I had to deal least with this 2 kinds of docstrings lately ,and I loved
it
so I suggest something like

class SuperDuper {
    # This class will help you
    # get your work done
    # w/o touching the keyboard

   function SuperDuper () {
     # TODO: document me
     // this kind of comment can mean `ignore me'
     //from ctor we can extract all the class attrs, with the convention
     // to let them be declare&initialized only here, w/o a `var'
statement.
      $this->foo = "bar";
   }
}

then, the classdoctpl.pl modified such it will get the corresponding doc
for each class/functions from there.
Also, considering the fact that the sources are parsed every time, we
can make another little cute script to strip them out and let the source
be small.

BTW: Massimiliano, you wrote
## This script is a VERY QUICK HACK(tm). If you follow phplib
codestyle
## should work. It works for me(tm), YMMV.

but where can I find the codestyle lined out? 

-- 
CIMPOESU Teodor, Web Programmer

@ DIGICOM S.A. Bucharest, Romania
@ Internet, site development
@ teo <email protected> , +(401)-330.47.28

official home page ~ http://www.digiro.net/
Internet  web page ~ http://internet.digiro.net/
-
PHPLIB Developers Mailing List. Send messages to <phplib-dev <email protected>>.
To unsubscribe, send "unsubscribe" to <phplib-dev-request <email protected>> in
the body, not the subject, of your message.