Android samples comments BEGIN_INCLUDE END_INCLUDE

Question

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?

Answer 1

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}

https://code.google.com/p/doclava/wiki/JavadocTags