I am discovering phpDocumentor to generate documentation from my php code. I achieved to generate a html file with the api documentation. But I found a tab called "class hierarchy diagram" which is empty. I looked on the documentation of phpDoc but there is no explication. Could you help me in generating this diagram ?
Thank you ?
Related
im searching for a Documentation Framework that supports the following features:
Generated from Code Comments
Searchable
Styling customizable
NTH: Linked references (If i reference a class somewhere class name should be linked to class documentation)
I want to use it to document an RESTfull API i'm working on
I know about YARDoc, but would be nice to gather some alternatives
Matt Silverman created a pretty comprehensive lists of what is available out there now for gen'ing docs from code.
http://www.mattsilverman.com/2013/02/tools-to-generate-beautiful-api-documentation.html
Apart from YARD, you can generate RDOC project documentation using the following rake task:
rake doc:app
After this, your docs will be located in the doc/app folder and can be viewed by opening the index.html file in your browser. It will include the (currently probably generic) doc/README_FOR_APP file.
Hope this helps :)
Any ideas on how to include the xsd:annotation and xsd:documentation content defined in the schema as javadoc in the generated pojo using jibx???
For now I only get the schema fragment on top of the class but cant see the annotation documentation for the schema.
thanks for you time.
You seem to be experiencing an unexpected behavior, unless the lack of details in your question threw this answer off... If you're still in a bind after attempting troubleshooting as described below, the best would be for you to update your request with more information, such as an XSD fragment showing the setup, the versions you're using (Java, JiBX) and the command line you use for your codegen utility.
Start by taking a look at customizations documentation; make sure that the import-docs option, which is responsible to "Convert xs:documentation annotations in the schema definition to Javadocs in the generated [...]", is not set to false. The default value is true, so it should work...
Check that from a command line perspective, you're not overriding it. Alternatively, you could ensure is set explicitly (see this).
JiBX does automatically includes xsd:documentation content in the generated source code which will end up in your javadocs.
For a nice example, take a look at the opentravel.org schema which is included in the JiBX schema library.
Here is the opentravel schema definition for a 'ping' message:
http://opentravel.org/2011B/OTA_PingRQ.xsd.
Now download and unzip the javadoc.jar for the generated code from maven central:
http://search.maven.org/#search%7Cga%7C1%7Cfc%3Aorg.jibx.schema.org.opentravel._2011B.ping.PingRQ
Notice how the xsd:documentation displays nicely in the javadoc.
Hope this example helps!
Don Corley
JiBX contributor
I am trying to use the <code> tag inside the <example> tag to show a sample code in xml documentation. However, when I build the Sandcastle project, I see that it is shown as C#. There is no language attribute in <code> tag. And I could not find a setting in Sandcastle's project properties. Am I missing something?
BTW, I am using HtmlHelp1 format.
Actually, if you move beyond Sandcastle to Sandcastle Help File Builder (SHFB),
you will get both an easier to use interface to Sandcastle and additional features for your documentation set, including just what you want: a language attribute (language) for the <code> element.
Note that SHFB generates a language selector menu but that only lets you
show or hide a particular set of languages (C#, VB.NET, C++, J#, JScript.NET, XAML, and JavaScript). It supports colorizing, though, of a larger set (C#, VB.NET, JScript.NET, C++, J#, C, JavaScript, VBScript, XAML, XML, HTML, SQL script, PowerShell script, and Python). (From the Code Block Component section of the SHFB documentation.)
I have written extensively on this point, as well as many other tips and pitfalls of Sandcastle and SHFB, in my article Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code published on Simple-Talk.com. Besides the main article, I also put together a wallchart/quick reference that gives you everything you need to know to use Sandcastle/SHFB on one page--the link also appears at the end of the article.
You can find more details about the <code> element in the Displaying Sample Code section of my article, as well as from the official SHFB documentation at Importing and Colorizing Code from Source Files.
i have created my own graphical editor using GMF.
i want to generate code based on the diagram created by editor? any pointers how to proceed
This might help you:
http://www.vogella.de/articles/EclipseBuilder/article.html
That page doesn't have the actual code example but the points to the necessary concepts: Builders. For example, the java compiler is hooked in through a builder that's registered for the .java type.
I'd love to ask you how do the guys developing dojo create the documentation?
From nightly builds you can get the uncompressed js files with all the comments, and I'm sure there is some kind documenting script that will generate some html or xml out of it.
I guess they use jsdoc as this can be found in their utils folder, but I have no idea on how to use it. jsDoc toolkit uses different /**commenting**/ notations than the original dojo files.
Thanks for all your help
It's all done with a custom PHP parser and Drupal. If you look in util/docscripts/README and util/jsdoc/INSTALL you can get all the gory details about how to generate the docs.
It's different than jsdoc-toolkit or JSDoc (as youv'e discovered).
FWIW, I'm using jsdoc-toolkit as it's much easier to generate static HTML and there's lots of documentation about the tags on the google code page.
Also, just to be clear, I don't develop dojo itself. I just use it a lot at work.
There are two parts to the "dojo jsdoc" process. There is a parser, written in PHP, which generates xml and/or json of the entirety of listed namespaces (defined in util/docscripts/modules, so you can add your own namespaces. There are basic usage instructions atop the file "generate.php") and a Drupal part called "jsdoc" which installs as a drupal module/plugin/whatever.
The Drupal aspect of it is just Dojo's basic view of this data. A well-crafted XSLT or something to iterate over the json and produce html would work just the same, though neither of these are provided by default (would love a contribution!). I shy away from the Drupal bit myself, though it has been running on api.dojotoolkit.org for some time now.
The doc parser is exposed so that you may use its inspection capabilities to write your own custom output as well. I use it to generate the Komodo .cix code completion in a [rather sloppy] PHP file util/docscripts/makeCix.php, which dumps information as found into an XML doc crafted to match the spec there. This could be modified to generate any kind of output you chose with a little finagling.
The doc syntax is all defined on the style guideline page:
http://dojotoolkit.org/reference-guide/developer/styleguide.html