g3doc format

[kmatzen]

Has the g3doc specification been publicly released? Is an effort going to be made so that outside contributors know exactly how comments should be written in order to be correctly parsed?

[Hello1024]

The g3doc used in Tensorflow is, I believe, identical to Markdown. If you find anything that doesn't meet the markdown specification, file an issue.

[kmatzen]

I mean the comments in the C++ that are used to generate the markdown files.

Example:
https://github.com/tensorflow/tensorflow/blob/master/tensorflow/core/public/env.h#L47

  /// \brief Returns a default environment suitable for the current operating
  /// system.
  ///
  /// Sophisticated users may wish to provide their own Env
  /// implementation instead of relying on this default environment.
  ///
  /// The result of Default() belongs to this library and must never be deleted.
  static Env* Default();

is used to generate

* [`static Env* tensorflow::Env::Default()`](#static_Env_tensorflow_Env_Default)
  * Returns a default environment suitable for the current operating system.

and

#### `static Env* tensorflow::Env::Default()` {#static_Env_tensorflow_Env_Default}

Returns a default environment suitable for the current operating system.

Sophisticated users may wish to provide their own Env implementation instead of relying on this default environment.

The result of Default() belongs to this library and must never be deleted.

My point is that the docs were pre-generated. I can't find another project where Google has open sourced the g3doc utility so that others may rerun it and update the documentation.

If the answer is "the syntax is just like doxygen", then that's an acceptable answer, although it would still be nice to be given the same tool to generate the markdown.

[martinwicke]

The syntax is, in fact, doxygen: part of our docs generation pipeline calls doxygen. We are working on making more of the doc generator publicly available, but it requires a decent amount of untangling.

[varun19299]

Is there a blog post or guide out for this yet?

[martinwicke]

Check out the documentation authoring guide: https://www.tensorflow.org/community/documentation