While reading some android samples I usually see comments like
// BEGIN_INCLUDE (something)
// END_INCLUDE (something)
However, my current IDE — Android Studio 1.1 — can not recognise them (or maybe I do something wrong). I guess, they serve as some kind of code region marks (like
//<editor-fold desc="Region name">
// some code
//</editor-fold>
in AndroidStudio/IntellijIDEA), but such syntax is much like c++ preprocessor directives. So the question: should I know something important about these comments (besides obvious commenting function) that could improve my code in any way?
It's for documentation purposes, used for identifying snippets to include in target documentation. It's not really useful when editing the code; it's useful for avoiding repetition by generating documentation from actual code.
{@sample} and {@include}
These tags copy sample text from an arbitrary file into the output javadoc html.
The @include tag copies the text verbatim from the given file.
The @sample tag
- copies the text from the given file and strips leading and trailing whitespace
- reduces the indent level of the text to the indent level of the first non-whitespace line
- escapes all <, >; and & characters for html
- drops all lines containing either BEGIN_INCLUDE or END_INCLUDE so sample code can be nested
Both tags accept either a filename and an id or just a filename. If no id is provided, the entire file is copied. If an id is provided, the lines in the given file between the first two lines containing BEGIN_INCLUDE(id) and END_INCLUDE(id), for the given id, are copied. The id may be only letters, numbers and underscore ().
Four examples:
{@include samples/SampleCode/src/com/google/app/Notification1.java} {@sample samples/SampleCode/src/com/google/app/Notification1.java} {@include samples/SampleCode/src/com/google/app/Notification1.java Bleh} {@sample samples/SampleCode/src/com/google/app/Notification1.java Bleh}