How to write code block using phpDocumentor, tutorials/extended documentation?

Question

How to write code blocks using phpDocumentor while writing tutorials/extended documentation?

I have tried <programlisting>, it can generate the <code> tag , but it does not parse its contents.

<refentry id="{@id}">  

 <refnamediv>  
  <refname>Guide for MyApp</refname>  
  <refpurpose>To demonstrate ...</refpurpose>  
 </refnamediv>  

 <refsynopsisdiv>  
  <author>  
   My Name
   <authorblurb>  
    {@link [email protected] My Name}  
   </authorblurb>  
  </author>  
 </refsynopsisdiv>  

 {@toc}  
 <refsect1 id="{@id intro}">  
  <title>User Guide for MyApp</title>  

  <para>  
   Some Description
  </para>

      <programlisting>

            $some = 'code';

      </programlisting>

 </refsect1>
</refentry>

Would you edit into your question an example of what you've tried? Do you mean within comment blocks before functions/methods? — halfer
– halfer, Commented Apr 23, 2013 at 8:30
No man , its not about comment blocks before functions , Its about writing tutorials/extended documentation. And that is different. — Antagonist
– Antagonist, Commented May 28, 2013 at 8:02

James Holderness · Accepted Answer · 2013-05-28 23:33:50Z

4

+100

This is actually very easy once you know how. You just need to set the role attribute on the programlisting element.

<programlisting role="php">
  $some = 'code';
</programlisting>

I couldn't find this documented anywhere, other than a brief mention in the release notes, but from looking at the code, there seem to be four roles that are supported:

php - adds PHP syntax highlighting to the content and includes a line number on every line.
tutorial - adds HTML syntax hightlighting to the content and includes a line number on every line.
xml - adds pre tags around the content, but otherwise no syntax hightlighting and no line numbers.
html - treats the content as raw HTML, so you can use whatever markup you like.

Any time you want to use angle brackets, though, you will need to escape those characters or wrap the content in a CDATA section. This even applies when you want to use raw HTML. If not, the parser will try and interpret the content as XML.

For example, a raw HTML sample would look something like this:

<programlisting role="html">
  <![CDATA[
    <b>This sentence will be bold.</b>
  ]]>
</programlisting>

Also note that all of this applies to the initial version of phpDocumentor. The new version (phpDocumentor 2) doesn't appear to support tutorials/extended documentation as far as I can tell.

edited May 28, 2013 at 23:33

answered May 28, 2013 at 22:16

James Holderness

23.1k2 gold badges43 silver badges52 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Antagonist Over a year ago

Tnx, this is exactly what I've been asking for.

Sina R. · Accepted Answer · 2013-05-09 12:52:38Z

4

+25

I checked it and I think you can use javascriptMVC documentation tool. I thik Documentation Tool.
and a demo of it is here. and I suggest you to try this.(-:

here is an output of documentJs of javascriptMVC which is /i think the thing you want. or at least I hope.(-: enter image description here

and about phpDocumentor As I said I need some explains to get what you mean but for now please check these. link1. link2 . (if the following is the thing you want).

 /** @type int This is a counter. */
 $int = 0;

 // there should be no docblock here
 $int++;

Or:

 /**
  * This class acts as an example on where to position a DocBlock.
  */
 class Foo
 {
     /** @type string|null Should contain a description if available */
     protected $description = null;

     /**
      * This method sets a description.
      *
      * @param string $description A text with a maximum of 80 characters.
      *
      * @return void
      */
     public function setDescription($description)
     {
         // there should be no docblock here
         $this->description = $description;
     }
 }

Another example is to document the variable in a foreach explicitly; many IDEs use this information to help you with auto-completion:

 /** @type \Sqlite3 $sqlite */
 foreach($connections as $sqlite) {
     // there should be no docblock here
     $sqlite->open('/my/database/path');
     <...>
 }

edited May 9, 2013 at 12:52

answered May 1, 2013 at 6:43

Sina R.

1,7782 gold badges19 silver badges38 bronze badges

7 Comments

Antagonist Over a year ago

I don't need javascript documentation ,The title says phpDocumentator.

Sina R. Over a year ago

@Antagonist ok just give me some time.

Sina R. Over a year ago

@Antagonist ok can you explain more what you mean than 'parse its contents' ?

Antagonist Over a year ago

Man I really appreciate your effort to help me , but I think you are going in wrong direction.I know how to write standard comment blocks.What I DON'T know is how to write code examples ( comments that contain code) while writing EXTENDED DOCUMENTATION.So you should first focus on the meaning of EXTENDED DOCUMENTATION also known as TUTORIALS.And the meaning of PARSE ITS CONTENTS : PhpDocumentator should be able to "understand" the comments (recognize the PHP language) , and display the code in different colors.For example: the word "class" should be colored in blue.

Antagonist Over a year ago

here is a link manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/… to see what I'm talking about

|

SP Singh · Accepted Answer · 2013-05-02 05:47:26Z

-2

You can user zend studio tool which can generate selected project documentation automatically

answered May 2, 2013 at 5:47

SP Singh

4364 silver badges18 bronze badges

Collectives™ on Stack Overflow

How to write code block using phpDocumentor, tutorials/extended documentation?

3 Answers 3

1 Comment

7 Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

1 Comment

7 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related