documentation

I have a method that return the current object, how do I document this? /** * set something * * @return this */ public function setSomething(){ // ... return $this; } Or should I do @return self or @return Current_Class_Name ? Reason why this question is not "primarily opinion-based" (and should be reopened): conformance to standards and IDE type hinting support. RiaD @return Current_Class_Name will definitely work and is what I prefer. @return self may work ok with some programs too. @return this is bad because this is not a typename. g . There is a PHP Standards Recommendation (PSR)

Private methods documentation can only be seen by who has access to the source code. Is it worth the effort spent on it? Personally, I feel that it is. Documentation is often the most useful to future developers maintaining your software - especially member documentation. Even public API documentation is only of limited use to any audience other than a developer. Document for those following - they will thank you. It definitely is. In anything but trivial software, you can make it faster to comprehend the code with the proper use of comments, even for the original author a few months later.

I've got some C++/CLI software which is all nice and documented in a C#'ish kind of way which means DOxygen is able to pull it out into some nice html. Is there any way I can get that same information to appear in the intellisense tool tips the way that the .net framework does? For example, lets say this is my header file (MyApp.h): /*************** MyApp.h ***************/ /// My namespace containing all my funky classes namespace MyNamespace { using namespace System; ref class WorldHunger; /// A truly elegent class which solves all the worlds problems public ref class MyClass { public: ///

I'm trying to do three really basic things inside of a multi-line math mode in Sphinx (version 1.1.2-1). Write underscores as part of my variable names even in math mode; Use the \big , \biggl , etc., delimiters to make large brackets and parentheses; and include regular text as part of equations. Note the following two things. (1) I am using a raw string in my Python code for the Sphinx-markup documentation, so extra backslashes are not needed for escape characters, and (2) I am not doing inline math mode, which is delimited like this in Sphinx: :math:`Some math stuff goes here` regular text

Is there a code/comment ratio that you consider to be a sign of good (bad) code health? Can you give examples of open source projects that are considered to be well coded and their respective comment ratio? (I realize that no ratio is "true" for every project and there may very well be crappy projects that exhibit this theoretical golden ratio. Still...) Comments should be very rare and valuable, almost always expressing the "why" and never the "how" (the exception being when the how is complex and not easily discernible from the code). Every comment is a hint that you may need to refactor to

Say I want to know if F# has a library function of type ('T -> bool) -> 'T list -> int ie, something that counts how many items of a list that a function returns true for. (or returns the index of the first item that returns true) I used to use the big list at the MSR site for F# before the documentation on MSDN was ready. I could just search the page for the above text because the types were listed. But now the MSDN documentation only lists types on the individual pages--the module page is a mush of descriptive text. Google kinda-sorta works, but it can't help with // compatible interfaces (

I'm documenting a few methods I wrote in C# that deal with parsing tokens. Due to some technical restraints in other areas of the system, these tokens need to take the form of XML elements (i.e., <tokenName /> ). I'd like to put the format of those tokens in the summary statement itself. However, this throws an error: Badly formed XML -- A name was started with an invalid character". Is there any sort of escape character sequence I can use to embed XML in my C# summary comments? Andrew Arnott Use standard XML escaping. For example: <summary>This takes a <token1> and turns it into a <token2><

I'm playing around with PHPDoc and have realised that you can use markdown to add some formatting to a DocBlock. In particular, I notice that you can use back ticks to highlight inline code. However, I can't seem to figure out how to add blocks of code to a DocBlock, as using 4 spaces doesn't seem to work. I've tried using <code> and <pre> too, and whilst those tags do appear in the generated documentation, the code inside them becomes commented out with HTML comments. For example, this DocBlock: /** * This is a test DocBlock * * <pre> * <?php * echo('hi'); * ?> * </pre> * * @return object[]

I'd like to reference a previously-documented function parameter elsewhere in a Python docstring. Consider the following (admittedly completely artificial) example: def foo(bar): """Perform foo action :param bar: The bar parameter """ def nested(): """Some nested function that depends on enclosing scope's bar parameter. I'd like to reference function foo's bar parameter here with a link, is that possible?""" return bar * bar # ... return nested() Is there a simple way to embed a parameter reference using Sphinx markup, or will this happen automagically? (I'm a complete Sphinx newbie. I've been