SCClassLibrary/Common/Helper/autoClassHelperTest.sc

   1 // a class testing autodoc. You will see some naming conventions and a special comment block
   2 // adding @ to multiline comment
   3 // In the following we try to test all the possible situations
   4
   5 /*
   6 You can use multiline comments here
   7 */
   8
   9 AutoClassHelperTest {
  10
  11         // this is a fake class indeed
  12
  13         /*@
  14         shortDesc: A class to test automatic documentation from source
  15         longDesc: The only limit of this tag is that it cannot break a line. This can be cumbersone, indeed. You can use <br> blocks. You will see that you have to specify in the source what you want to document. Note in any case that for specified args in method the default value is extracted automatically. Works with the Class template (no sense for UGens).
  16         seeAlso: Homunculus, Leviathan
  17         issues: Caution! Frailty thy name is AutoClassHelper. You can omit tags but in order to have it running you cannot change their order. More, it works only for the first class defined in a source file. Note also that actually it assumes that you have one class for sourcefile.  It crashes if there's no class desc block. If method block descriptions are not indented as demonstrated they are not recognized properly. <br> Please use conventions specified in this class source file.
  18         testvar: nothing special
  19         classtestvar: really interesting
  20         instDesc: How to become an anthropogenist
  21         longInstDesc: It's easy. Consider using the following methods.
  22         @*/
  23
  24         var <>testvar, <another, >one, last ;
  25         // if you like to comment here, you can
  26         classvar classtestvar ;
  27
  28         *new { arg ens = "Adam";
  29
  30                 // if you like to comment here, you can
  31                 // for each method you can (optionally) provide
  32                 // desc: a description line
  33                 // arg: each argument
  34                 // ex: a (multiline) example
  35
  36                 /*@
  37                 desc: creation is typically reserved to God. Args follows.
  38                 ens: it's a good start
  39                 ex:
  40                 // a multiline example is possible
  41                 // assuming that ex tag is the LAST one
  42                 // a pity: no colored syntax
  43                 TestClass.new("Eve").postln ; // comment
  44                 TestClass.class.postln ;
  45                 k = \aSymbol ;
  46                 j = "a string" ;
  47                 @*/
  48                 // if you like to comment here, you can
  49                 ^super.new.init(ens);
  50         }
  51
  52         *open { arg ensPattern ;
  53                 // nothing should appear in docs
  54                 "creating from a mould".postln ;
  55         }
  56
  57         init { arg testArg ;
  58                 // here we omit description
  59                 ^testArg ;
  60         }
  61
  62 /*
  63 Maybe you want to separate blocks of source code
  64 with multiline.
  65 You can, indeed
  66 */
  67
  68 // start working stuff
  69
  70         generate { arg fromScratch = true, deus ;
  71                 /*@
  72                 fromScratch: whether you're a real constructivist or not
  73                 deus: sive natura (as you prefer)
  74                 @*/
  75                 "I like test".postln ;
  76         }
  77
  78         destroy { arg ens, method = \evaporate ;
  79                 /*@
  80                 desc: it's a dirty job, but someone's got to do it
  81                 method: there are many options. Quite efficient implementation
  82                 @*/
  83                 ^nil
  84         }
  85
  86         makeBadKarma { arg ens, toMineral = true ;
  87                 /*@
  88                 desc: "you can't always get what you want"
  89                 toMineral: back to the roots
  90                 ex:
  91                 k = AutoDocTestClass.new ;
  92                 k.makeBadKarma(toMineral: false) ;
  93                 @*/
  94                 ^nil
  95         }
  96
  97 // stop real working stuff
  98
  99 }
 100
 101
 102 // only the first class in a source file can be documented.
 103 // If you ask for autodoc on AutoDocTestClass2, e.g.
 104 //              AutoClassHelper(AutoDocTestClass2)
 105 // SC raises an error.
 106 // If AutoDocTestClass2 is in a separate file, all is ok.
 107 // Note that at least you need a /*@@*/ block in the class you need to document,
 108 // otherwise SC raises an error
 109 // (well, does not make sense to autogenerate ah help file from no provided infos)
 110
 111
 112 AutoDocTestClass2 {
 113
 114
 115         print { arg first, second ;
 116                 [first, second].postln ;
 117         }
 118
 119         test { arg aTest ;
 120                 /*@
 121                 desc: "Saigon, shit, I'm still only in Saigon"
 122                 @*/
 123                 aTest.postln ;
 124         }
 125
 126
 127 }