I am new to Doxygen but I want to use it for a technical documentation for our team.
The background: We have several services in .NET which are going to be called from a JAVA backend through RPC.
Therefore it is quite useful to have those services documented for the JAVA guys.
Using the Doxywizard did help in the first place, but it created a huge overflow of data, which I want to filter, but have no clue how to.
What I want to achieve is, that Doxygen ONLY will use methods, which does have a specific attribute.
For example:
[RpcMethod(id: "GetNumDemo", description: "A demo method")]
public async Task<int> GetNumDemo(JavaDTO dtoObject, int randNum)
I want to have the method within the documentation found by Doxygen since it has the RpcMethod attribute and also cause it have a JavaDTO object, I want to have this class documented as well.
But I am overwhelmed with it ... do you guys can help me? ... at least with a hint within the Doxygen documentation.
Read through the documentation and goodled
Related
I have an OO project in MATLAB and would like to automatically produce some documentation.
After some research I have found a convenient tool called mtoc++ which apparently produces a documentation using Doxygen (I have no experience with).
My only question is whether in order to use the tool I need to write comments in MATLAB using a specific format (language?) so that mtoc++/Doxygen could understand and document my comments?
If so, then what this format/ language is and where I can find its description?
After correctly installing and configuring mtoc++/Doxygen, the documentation is created automatically.
If you want to define personalized comments for specific custom parameters, you can follow the instructions on this page:
http://www.ians.uni-stuttgart.de/MoRePaS/software/mtocpp/docs/tools.html
Look under the heading Configuration options for the mtoc++ filter.
What you have to do is to edit the mtocpp.conf file, located in tools/config folder, and the format you'll be using is this:
add(params) = <parameter1_name> => """Your parameter1 description text in triple quotes""";
An example would be:
add(params) = myVariable => """This variable is defined by me""";
So you can define personalized comments for your Parameters, Fields, Extra Documentation and Global Settings.
I am sure there must be other workarounds to add comments and documentation.
I hope this helps. Happy coding.
After looking around for a while I was able to understand how the json: tags are used in the Go language. However two tags I have come across I'm still lost on, and can't seem to find documentation on it.
Both pertain to a REST api service and the full code can be found here-> code.google.com
What is the root: tag used for
gorest.RestService `root:"/orders-service/" consumes:"application/json" produces:"application/json"`
as well how does the method: tag work?
userDetails gorest.EndPoint `method:"GET" path:"/users/{Id:int}" output:"User"`
I didn't know if anyone had any links to a site or document that might explain this more, from the examples I can learn enough to use it. However, I would really like to fully understand it.
Thanks for your time!
Tags are nothing but strings, they don't have any meaning per-se.
Libraries can use reflection to introspect struct fields and interpret their tags. See reflect.StructTag.
In your case, gorest parses the following tags on Services:
root
consumes
produces
and these on Endpoints:
realm
method
path
output
input
role
postdata
Their meaning is described in gorest's documentation.
These are gorest tags. See gorest wiki http://code.google.com/p/gorest/wiki/GettingStarted
(I am also using .NET 4.0 and VS 2010.)
I created a function import returning a complex type, as explained at http://msdn.microsoft.com/en-us/library/bb896231.aspx. The function import and new complex type appear in my .edmx file and in the Designer.cs file. However, the function does not appear when I view the service in the browser, and when I add or update a service reference in the client project, the function does not appear there either - as is to be expected, given the first result.
Creating an imported function and using it seems conceptually very simple and straightforward, and one would think it would just work, as Microsoft's step-by-step instructions appear to suggest: http://msdn.microsoft.com/en-us/library/cc716672.aspx#Y798 (which article shows the SP returning entity types - I tried this also, and it doesn't work for me either).
This blog post shows the addition of a method to the DataService class, which Microsoft's instructions omit: http://www.codegain.com/articles/wcf/miscellaneous/how-to-use-stored-procedure-in-wcf-data-service.aspx I tried adding one method returning a list of entity types and another returning a list of complex types, and still had no success. I still could not access the functions, either directly via the browser or from the client application via a service reference.
Thanks in advance for any help with this.
config.SetServiceOperationAccessRule("*", ServiceOperationRights.All);
MS would do well to add a note to the walkthroughs stating that the above bit of code must be there. (It may be better to enable each operation explicitly than to use "*".)
http://www.codegain.com/articles/wcf/miscellaneous/how-to-use-stored-procedure-in-wcf-data-service.aspx shows that line of code. Also, something it is there in the code, commented out, when one creates the WCF Data Service. Some of us like to delete commented-out code that we aren't using and that seems irrelevant - perhaps doing so a bit prematurely, sometimes.
I'm new to CoffeeScript and seems that I can't find any document generator for CoffeeScript using Javadoc syntax. The only one I could find is available as a patch to the CoffeeScript compiler.
So, what do you use to generate documentation from Javadoc comment on CoffeeScript or how do you document your function arguments and return values?
So, JavaDoc syntax has never really caught on with JavaScript developers. There are those who use something like it—notably Google—but it's kind of at odds with JS, which doesn't have static typing and allows any number of arguments to any function.
If you want to create beautiful documentation with CoffeeScript, the standard is Docco (its home page is an excellent example). If you want to create JavaDoc-style comments for every function... well, you'll have to create them by hand, and escape them with backticks.
Alternatively, you could work in CoffeeScript until your code is release-ready, then document the resulting JavaScript.
Docco is great for prozedural coding style. If you want to document an API, coffeedoc is for you.
People looking forward to using javadoc style documentation in coffeescript can checkout codo ( http://netzpirat.github.com/codo/ ) which provides support for a subset of javadoc and automatically infers class names, function names and parameters from source code.
I'm using YUIDoc. I can add comments using a syntax similar to Javadoc to my classes, methods and events. The documentation gets output as html/css files and you can even customize the page layout.
Check this documentation example: http://yui.github.com/yuidoc/api/
PS: It relies on Node.JS and you need to install the package yuidocjs
npm install yuidocjs -g
I'm a big fan of GhostDoc's automatic comment generation in Visual Studio so am looking for an plugin that does the same job with my Java code in Eclipse. Any recommendations?
You can check JAutodoc (http://jautodoc.sourceforge.net/)
From the author:
JAutodoc is an Eclipse Plugin for
automatically adding Javadoc and file
headers to your source code. It
optionally generates initial comments
from element name by using Velocity
templates for Javadoc and file
headers.
This one is the one I've found closest to GhostDoc.
It is basically the equivalent of Javadoc, which can be generating in eclipse with the shortcut:
ALT+Shift+J
(when you are within the Java function you wish to add javadoc for)
From there, if you really want XML format, you can try and use a JELDoclet
GhostDoc has a nice extra feature that infers a description of what the method does by parsing the method name and providing this as skeletal documentation. For example, using GhostDoc on a method named GetDocumentName() might return the phrase "Gets the document name". While this is hardly more information than provided by the method name, it adds method documentation where previously none existed. Some might argue that this is barely useful. I argue to the contrary because it supports generating documentation from the source code (e.g., for tools like NDoc or SandCastle).
In my opinion the greatest benefit of GhostDoc over eclipse's "Generate Element Comment" is that it encourages programmers to begin adding documentation comments by adding an extremely fast and reliable way create this. The programmer can accept the inferred text, (suitable in 50 - 80% of cases), or expand on this for more complex methods. For the junior programmer who is not as familiar with how documentation comments are used, this can quickly shorten the learning curve and encourage good programming practices.
Javadoc is not like GhostDoc my friend. Javadoc only creates the structure so one can write the documentation from scratch. GhostDoc actually fills up the information according to the Method/Property name.
Example:
/// <summary>
/// Gets the user from id.
/// </summary>
/// <param name="id">The id.</param>
/// <returns></returns>
private string GetUserFromId(string id);
JAutoDoc is the closest I've found so far but it's not as magical as GhostDoc.
Never used GhostDoc, so not sure what extra functionality it gives, but if it's about generating type and method comments based on the name, parameters, return type etc. then eclipse has it built in, so no extensions needed.