Basically I want to write one piece of text which qualifies both as a working code and MarkDown (preferably GitHub flavor) for documentation. The language I'm using has C form commenting \\ for rest-of-line and /* ... */ for multi line comments. So far what I can do is:
/* --> start with multi line comments
here some markdown text
# heading
* list
end markdown section with
<!--- */ // -->
or
[//]: # (end of comment block --> */ // <-- inline comment)
_-_-indented code
_-_-_-_-more indented code
The issues are:
the first /* still showing in the documentation
I can't use the proper multiline code block ``` ... ```. I have to indent the code parts once more than what is required. Also the syntax highlighting doen't work in this format AFIK.
I would appreciate if you could help me know first how to solve above issues. and Secondly if there is any better way to do this?
I think I have a proper solution now with colapsible / foldable code section:
/*
This is the markdown **text**
used for documentation
<details>
<summary>Click to see the source code</summary>
``` scilab
*/
This is the
actual code
which will
be executed
/*
```
</details>
<!--- */ // -->
which will be rendered as:
/*
This is the markdown text
used for documentation
*/
This is the
actual code
which will
be executed
/*
The collapsible section makes sure that the documentation is clean and readable. you may see the final result here on GitHub. I used the code from here. Now there are a bunch of /*s and */s which would be nice to get ride of. Next step would be to modularize the MarkDown document into different files as I have asked here.
P.S. Implementation of the same idea using AsciiDoc here.
Is there a way to comment M code / comment out lines or blocks of code?
M supports two different types of comments:
Single line comments can be started with //
You can comment out multiple lines or comment out text in the middle of a line using /* */ (e.g. = 1 + /* some comment */ 2)
Comments might seem to disappear in the formula bar if they are at the end of the line, but they are still there. You can verify this by looking at your code in the Advanced Editor.
In Visual Studio you can minimize huge chunks of code using regions; they essentially just surround the code and minimize it in the window.
Does Sublime have a feature similar to this?
By default, you can select some code the go to Edit > Code Folding > Fold. There are tons of plugins that leverage the code-folding api for more options.
There's a request on the official site to "ask for features" here.
But apparently:
FYI, Jon has stated that this is not possible in the current
implementation of the editor control. Looks like we're waiting till V3
guys.
Jon being the programmer behind Sublime Text 2.
There might be a way to fake it by creating a plugin that looks for markers and removes the code region in between the markers, but it probably wouldn't look good. With the current API, it's probably your best bet!
By the way, there is some code folding in Sublime Text, if you hover your mouse next to the line number, you will see some arrows appearing when you can fold / unfold.
I ended up using custom comment tags, indented one level less than the code I want to fold. It doesn't look best, though it serves its purpose.
class Foobar {
// ...some code
// <fold
function foo() {
}
function bar() {
}
// </fold
// more code...
}
This (at the moment) folds to:
class Foobar {
// ...some code
// <fold[...]
// </fold
// more code...
}
Having a native ST2 support for this would be nice.
This looks what you are looking for. You can define tags for #region and #endregion for each language, or a generic tag for all of them.
If you are obsessed with intendation, this solution may make you uncomfortable but here it is, once upon a time while I had been writing a semi-complex jQuery plugin I've had constants, variables, private and public functions sections and foldings like so;
;(function($, undefined, window) {...
/* Consts */
var FOO = "BAR";
/* Variables */
var m_Foo = "bar";
/* Functions */
/* Public Functions */
function foo() {...}
function bar() {...}
/* Private Functions */
function _foo() {...}
function _bar() {...}
})(jQuery, window);
As you can see it is all about intendation. Sections can be folded; Consts, Variables, Functions. And also inside Functions section, Public Functions and Private Functions are both can be folded.
You can also use one line comment (//) to name your fold. So the idea underneath that is simple; ST2 thinks that the more intended lines belongs to first less-intended comment above them, like C/C++ compilers how handle brackets as own unique code blocks.
To fold the code select the code and press
ctrl + shift + [
To unfold the code put the cursor there and press
ctrl + shift + ]
I think that like myself, the OP has come to appreciate a little-known feature in VS called regions that many equate to code-folding, but is FAR more powerful and above, Dio Phung provided the answer that I wanted, and I suspect the OP wanted, but he didn't share as an answer so here it is.
The difference between "code-folding" as it's provided in Sublime Text is that it's based on code/compiler syntax while "regions" and what this plugin does, allow you infinitely more freedom, though it's a freedom that's more or less dependant on the code you're working with to begin with (deeply nested, or properly modularized).
If you are on Sublime Text 3, here is a plugin that can do it :
github.com/jamalsenouci/sublimetext-syntaxfold – Dio Phung
In languages which support 3 types of comments (e.g. PHP) I use the hashtag comment for regions, as shown in the other answers. It's also good for keeping track of what's being done
# default options
$a = 3;
$b = 'bob';
$old_code = 1;
# bugfix #130
$result = magic_function($data);
fix_stuff($result);
$old_code = $result;
Otherwise use triple slash ///, or //# etc.
In sublime text, it works like this, it shades the lines you want to collapse and presses (Control + Shift +?)
I have the most recent version of sublimetext.
When using nerd commenter in visual mode, the first line is commented differently.
Initial code
const IMG_SIZE_SMALL = '32x32';
const IMG_SIZE_MEDIUM = '64x64';
const IMG_SIZE_LARGE = '192x192';
After doing ,cc in visual mode selecting these lines.
/* const IMG_SIZE_SMALL = '32x32';*/
//const IMG_SIZE_MEDIUM = '64x64';
//const IMG_SIZE_LARGE = '192x192';
What should I do so that the first line is also commented out using // ?
You didn't mention what filetype the file has. I tried creating a small test.c file with only the lines provided in your question and used ,cc to comment out the lines. I tried two different filetype settings. With filetype=c, the lines were all commented out with /* --- */ style comments and with filetype=cpp, the lines were all commented out with // style comments. Have you made sure you are using the latest version of NERD_commenter (2.2.2)?
Ok, now I created a small test file with these lines and some testing lines above and below them. NERD commenter comments them all with the same //-style comments. You don't happen to be selecting lines in character-wise mode? That is pressing v instead of shift-v to select the lines? When i tried that i was able to get different comment styles for some lines.
In VS 2008, there are XML code snippets that seem to be pretty awesome :) However, it seems that the snippets we created do not indent properly. For example if we have the following code:
{
...
{
...
{
InsertSnippet here.
We get something like:
{
...
{
...
{
FirstLineofSnippet
SecondLineOfSnippet
ThirdLineOfSnippet
Is there any way to make it so that all lines keep the same indentation?
This usually indicates that the code you are inserting is semantically incorrect - at the time of insert, not when you filled in the snippet values.
To prevent this you can use default values in your snippet to make the snipped syntactivaly correct. E.g. to declare an argument list for a function:
<Literal Editable="true">
<ID>methodArguments</ID>
<ToolTip>methodArguments</ToolTip>
<Default>params object[] args</Default>
<Function>
</Function>
</Literal>
The <Default> Element provides the declaration. So using this in a snippet declaring a funciton will lead to this:
public void FunctionName(params object[] args) { }
And it then lets you replace params object[] args with whatever argument declarations you need.
paste the first line without indentation, then select the block and tab until you get the whole block to the indentation you want. AFAIK what you see is the standard behavior and it happens because the location you paste from wasn't indented as far as you wanted.
My unit test snippet appears to be indenting correctly. It may be due to the fact that the code is wrapped in a CDATA block. VisualStudio also tends to auto-format the block as soon as it is added to the code. Does your snippet have as many open braces as closing ones? If the two match up, and the snippet is inserted in a valid/compilable location, it should auto-format.
It seems that Visual Studio does an auto-format on the inserted lines. My snippet wasn't correctly formatted (i.e. indented) either, neither by snippet insertion, nor by manual format (Ctrl-K-F). It contained "delegate{...}", maybe the formatter cannot handle this.
Try swithing from Insert spaces to Keep tabs in Tools > Options > TextEditor > C# > Tabs, it worked for me.