You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4php-dev@logging.apache.org by Curt Arnold <ca...@apache.org> on 2009/11/20 04:38:41 UTC
Use of {@example}'s line number to tolerate ASF source license header (was Re: [VOTE] Create release based on Log4PHP-2.0.0 RC1)
The {@example} directive can optionally take an starting line number (http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineexample.pkg.html). I've played with it with LoggerMDC.php and it would seem to allow us to add the ASF source license header to the example PHP and .properties files without adversely affecting the generated output (unless you really need to code snippets in the docs to have the leading <?php.
I'm guessing that Doxia's snippet handler automatically closes a snippet at the end of the file, so setting the line number just beyond the // START SNIPPET and removing the // END SNIPPET eliminates those artifacts from the phpdocs.
The magic line number for .php files for me was 19 for .php files and 18 for .properties files.
The LoggerMDC.php contained the line "The MDC is managed on a per thread basis" 3 times. Also, the <p><b><i> was rendered so a literal "<i>" was visible in the generated documentation. Bold and italic and repetition seems extreme.
Re: Use of {@example}'s line number to tolerate ASF source license
header (was Re: [VOTE] Create release based on Log4PHP-2.0.0 RC1)
Posted by Christian Grobmeier <gr...@gmail.com>.
> Time for RC2?
Yeah, will start on it tomorrow :)
Thanks !
>
> bye,
>
> -christian-
>
> Am Thu, 19 Nov 2009 21:38:41 -0600
> schrieb Curt Arnold <ca...@apache.org>:
>
>> The {@example} directive can optionally take an starting line number
>> (http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineexample.pkg.html).
>> I've played with it with LoggerMDC.php and it would seem to allow us
>> to add the ASF source license header to the example PHP
>> and .properties files without adversely affecting the generated
>> output (unless you really need to code snippets in the docs to have
>> the leading <?php.
>>
>> I'm guessing that Doxia's snippet handler automatically closes a
>> snippet at the end of the file, so setting the line number just
>> beyond the // START SNIPPET and removing the // END SNIPPET
>> eliminates those artifacts from the phpdocs.
>>
>> The magic line number for .php files for me was 19 for .php files and
>> 18 for .properties files.
>>
>> The LoggerMDC.php contained the line "The MDC is managed on a per
>> thread basis" 3 times. Also, the <p><b><i> was rendered so a literal
>> "<i>" was visible in the generated documentation. Bold and italic
>> and repetition seems extreme.
>
Re: Use of {@example}'s line number to tolerate ASF source license
header (was Re: [VOTE] Create release based on Log4PHP-2.0.0 RC1)
Posted by Christian Hammers <ch...@lathspell.de>.
Hello
That was a good hint. I did as you suggested and now RAT is happy.
The MDC and NDC phpdoc looks proper again, too.
Time for RC2?
bye,
-christian-
Am Thu, 19 Nov 2009 21:38:41 -0600
schrieb Curt Arnold <ca...@apache.org>:
> The {@example} directive can optionally take an starting line number
> (http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineexample.pkg.html).
> I've played with it with LoggerMDC.php and it would seem to allow us
> to add the ASF source license header to the example PHP
> and .properties files without adversely affecting the generated
> output (unless you really need to code snippets in the docs to have
> the leading <?php.
>
> I'm guessing that Doxia's snippet handler automatically closes a
> snippet at the end of the file, so setting the line number just
> beyond the // START SNIPPET and removing the // END SNIPPET
> eliminates those artifacts from the phpdocs.
>
> The magic line number for .php files for me was 19 for .php files and
> 18 for .properties files.
>
> The LoggerMDC.php contained the line "The MDC is managed on a per
> thread basis" 3 times. Also, the <p><b><i> was rendered so a literal
> "<i>" was visible in the generated documentation. Bold and italic
> and repetition seems extreme.